mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-17 18:32:19 +02:00
Merge origin/main (v1.60.1.0) into garrytan/gstack-fix-wave
Semantic reconciliation with the parallel time-attack wave (#2264):
- careful: adopt main's anchored full-command whitelist (stricter — also
catches comment-hiding), re-apply this wave's two hardenings on top
(capital -[rR] in the flag cluster; exclude `(` and backtick from safe
targets so $()/backtick substitution cannot ride the whitelist). Union
of both waves' test batteries passes (main's test.each incl. comment
case + this wave's substitution/capital-R/FP-pin cases).
- one-way-doors: main landed the singular noun unification (a2a447a1);
keep this wave's superset (plural s? + --summary-stdin runtime wiring).
- gbrain-local-status: union of states — main's engine-locked (#2194,
exit 124 PGLite lock) + this wave's thin-client (#2051). --is-ok keeps
main's intent (engine-locked = STOP) and this wave's (thin-client =
usable). Test harness unions both fake behaviors.
- sync-gbrain/setup-gbrain tmpls: both Step 1.5 branches kept; generated
SKILL.md resolved via bun run gen:skill-docs (never hand-edited).
- VERSION/package.json -> 1.61.0.0 per bin/gstack-next-version (main took
1.60.1.0; PR #2470 claims 1.60.2.0). CHANGELOG: wave entry renumbered
1.61.0.0 on top of main's 1.60.1.0; careful/#2024 bullets updated to
describe the delta vs current main. TODOS: union.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
+39
-15
@@ -869,17 +869,33 @@ fi
|
||||
## Phase 1: Read source, plan codegen
|
||||
|
||||
1. Walk the app source (passed as `--source <dir>`) and identify all `@Observable`
|
||||
classes. Note any property marked with the `@Snapshotable` wrapper — those
|
||||
are the snapshot-eligible fields.
|
||||
2. Run `swift run --package-path $GSTACK_HOME/ios-qa/scripts/gen-accessors-tool gen-accessors --input <source-dir>`.
|
||||
First invocation builds the swift-syntax dependency tree (cold: 2-5 min).
|
||||
Subsequent runs are content-hash-cached and finish in ~50ms.
|
||||
3. Show the user the accessor list and ask whether to install the DebugBridge
|
||||
classes. Note any property immediately preceded by the generator marker
|
||||
comment `// @Snapshotable` — those are the snapshot-eligible fields. The
|
||||
marker is a comment so it composes with the `@Observable` macro. Each
|
||||
marked field must belong to a file-scope observable class and be a writable
|
||||
instance `var` with an explicit type and an internal or public setter.
|
||||
Snapshot types are JSON-native scalars (`String`, `Bool`, integer widths,
|
||||
`Float`, `Double`, `CGFloat`), arrays, String-keyed dictionaries, and their
|
||||
Optional compositions. Keys must be unique across observable classes.
|
||||
Codegen stops with a source diagnostic instead of emitting a broken or
|
||||
lossy harness when any of these constraints is violated.
|
||||
2. Show the user the accessor list and ask whether to install the DebugBridge
|
||||
SPM dependency into their `Package.swift` (one AskUserQuestion).
|
||||
|
||||
## Phase 2: Bootstrap the device bridge
|
||||
|
||||
1. Add the `DebugBridge` SPM dependency to the app's `Package.swift`. The package
|
||||
1. Generate the canonical local bridge package, typed accessors, and installed
|
||||
version marker with one deterministic command:
|
||||
```bash
|
||||
~/.claude/skills/gstack/bin/gstack-ios-qa-regen \
|
||||
--app-source "<source-dir>" \
|
||||
--bridge-dir "<source-dir>/DebugBridge"
|
||||
```
|
||||
The regenerator also removes the explicit obsolete flat-file set created by
|
||||
older ios-sync versions, preventing a stale second harness from remaining
|
||||
in the app target.
|
||||
2. Add the generated `DebugBridge` local SPM dependency to the app's
|
||||
`Package.swift`. The package
|
||||
ships three Debug-config-only library products:
|
||||
- `DebugBridgeCore` (Swift, cross-platform) — StateServer + bridge protocols.
|
||||
- `DebugBridgeTouch` (Objective-C, iOS-only) — KIF-derived in-process touch
|
||||
@@ -889,27 +905,35 @@ fi
|
||||
The app target depends on `DebugBridgeUI` with `.when(configuration: .debug)`
|
||||
(transitively pulls in Core + Touch). Release builds refuse to link these
|
||||
targets.
|
||||
2. Wire the bridges from the `@main` App init, gated on `#if DEBUG`:
|
||||
3. Wire the bridges from the `@main` App init, gated on `#if DEBUG`:
|
||||
```swift
|
||||
#if DEBUG
|
||||
import DebugBridgeCore
|
||||
StateServer.shared.start()
|
||||
#if canImport(UIKit)
|
||||
import DebugBridgeUI
|
||||
// Install resolvers before StateServer opens its listener.
|
||||
DebugBridgeUIWiring.installAll()
|
||||
#endif
|
||||
// Replace AppState/AppStateAccessor with the type discovered in Phase 1.
|
||||
DebugBridgeManager.shared.start(
|
||||
appState: appState,
|
||||
register: AppStateAccessor.register
|
||||
)
|
||||
#endif
|
||||
```
|
||||
3. Build + deploy to the device with `xcodebuild -scheme <SchemeName>
|
||||
4. Build + deploy to the device with `xcodebuild -scheme <SchemeName>
|
||||
-destination 'platform=iOS,id=<UDID>' build install`.
|
||||
4. Launch via `devicectl device process launch --device <UDID> --console <bundle-id>`.
|
||||
5. Launch via `devicectl device process launch --device <UDID> --console <bundle-id>`.
|
||||
Capture the boot token printed to `os_log` on first run.
|
||||
5. Spawn the Mac-side daemon (on-demand) — `gstack-ios-qa-daemon`. Daemon
|
||||
6. Spawn the Mac-side daemon (on-demand) — `gstack-ios-qa-daemon`. Daemon
|
||||
acquires an exclusive flock on `~/.gstack/ios-qa-daemon.pid`. If another
|
||||
daemon is alive, the second invocation discovers its port and connects.
|
||||
6. Daemon immediately calls `POST /auth/rotate` on the iOS StateServer with a
|
||||
7. Daemon immediately calls `POST /auth/rotate` on the iOS StateServer with a
|
||||
fresh in-memory-only token. The boot token becomes useless ~5s later.
|
||||
Anything scraping `os_log` past this point sees a dead credential.
|
||||
If a fresh daemon finds the app running after another daemon consumed that
|
||||
one-use token, it verifies the bundle owner, relaunches the target once,
|
||||
waits for the new token, verifies ownership again, and then rotates.
|
||||
|
||||
## Phase 3: Vision-driven agent loop
|
||||
|
||||
@@ -917,7 +941,7 @@ Each iteration:
|
||||
|
||||
1. `GET /screenshot` (via daemon) → save PNG.
|
||||
2. `GET /elements` → accessibility tree.
|
||||
3. `GET /state/snapshot` (only `@Snapshotable` fields) → current state.
|
||||
3. `GET /state/snapshot` (only `// @Snapshotable` fields) → current state.
|
||||
4. Decide next action based on what's on the screen vs the test goal.
|
||||
5. `POST /session/acquire` to grab the device lock.
|
||||
6. Execute `POST /tap`, `/swipe`, `/type`, or `POST /state/<key>` write.
|
||||
@@ -981,7 +1005,7 @@ live.
|
||||
| `curl: connection refused` to daemon | daemon crashed | Re-run `/ios-qa`; spawn-race lock will fail closed |
|
||||
| `403 identity_not_allowed` from `/auth/mint` | identity missing from allowlist | Run `gstack-ios-qa-mint --remote <identity>` on the Mac |
|
||||
| `409 schema_mismatch` on `/state/restore` | snapshot from older app build | Discard the snapshot; re-capture |
|
||||
| `503 device_disconnected` from proxy | USB tunnel dropped | Reconnect device; daemon auto-reconnects within 30s |
|
||||
| `503 device_disconnected` from proxy | USB route dropped or app relaunched | Daemon invalidates the stale tunnel and retries one fresh bootstrap; reconnect/unlock the iPhone if it persists |
|
||||
| `429 rate_limited` from `/auth/mint` | >10 mints/min from one identity | Wait 60s; check audit log for anomalies |
|
||||
| `413 body_too_large` on `/state/restore` | snapshot >1MB | Increase `--max-body` or trim snapshot |
|
||||
|
||||
|
||||
+39
-15
@@ -97,17 +97,33 @@ fi
|
||||
## Phase 1: Read source, plan codegen
|
||||
|
||||
1. Walk the app source (passed as `--source <dir>`) and identify all `@Observable`
|
||||
classes. Note any property marked with the `@Snapshotable` wrapper — those
|
||||
are the snapshot-eligible fields.
|
||||
2. Run `swift run --package-path $GSTACK_HOME/ios-qa/scripts/gen-accessors-tool gen-accessors --input <source-dir>`.
|
||||
First invocation builds the swift-syntax dependency tree (cold: 2-5 min).
|
||||
Subsequent runs are content-hash-cached and finish in ~50ms.
|
||||
3. Show the user the accessor list and ask whether to install the DebugBridge
|
||||
classes. Note any property immediately preceded by the generator marker
|
||||
comment `// @Snapshotable` — those are the snapshot-eligible fields. The
|
||||
marker is a comment so it composes with the `@Observable` macro. Each
|
||||
marked field must belong to a file-scope observable class and be a writable
|
||||
instance `var` with an explicit type and an internal or public setter.
|
||||
Snapshot types are JSON-native scalars (`String`, `Bool`, integer widths,
|
||||
`Float`, `Double`, `CGFloat`), arrays, String-keyed dictionaries, and their
|
||||
Optional compositions. Keys must be unique across observable classes.
|
||||
Codegen stops with a source diagnostic instead of emitting a broken or
|
||||
lossy harness when any of these constraints is violated.
|
||||
2. Show the user the accessor list and ask whether to install the DebugBridge
|
||||
SPM dependency into their `Package.swift` (one AskUserQuestion).
|
||||
|
||||
## Phase 2: Bootstrap the device bridge
|
||||
|
||||
1. Add the `DebugBridge` SPM dependency to the app's `Package.swift`. The package
|
||||
1. Generate the canonical local bridge package, typed accessors, and installed
|
||||
version marker with one deterministic command:
|
||||
```bash
|
||||
~/.claude/skills/gstack/bin/gstack-ios-qa-regen \
|
||||
--app-source "<source-dir>" \
|
||||
--bridge-dir "<source-dir>/DebugBridge"
|
||||
```
|
||||
The regenerator also removes the explicit obsolete flat-file set created by
|
||||
older ios-sync versions, preventing a stale second harness from remaining
|
||||
in the app target.
|
||||
2. Add the generated `DebugBridge` local SPM dependency to the app's
|
||||
`Package.swift`. The package
|
||||
ships three Debug-config-only library products:
|
||||
- `DebugBridgeCore` (Swift, cross-platform) — StateServer + bridge protocols.
|
||||
- `DebugBridgeTouch` (Objective-C, iOS-only) — KIF-derived in-process touch
|
||||
@@ -117,27 +133,35 @@ fi
|
||||
The app target depends on `DebugBridgeUI` with `.when(configuration: .debug)`
|
||||
(transitively pulls in Core + Touch). Release builds refuse to link these
|
||||
targets.
|
||||
2. Wire the bridges from the `@main` App init, gated on `#if DEBUG`:
|
||||
3. Wire the bridges from the `@main` App init, gated on `#if DEBUG`:
|
||||
```swift
|
||||
#if DEBUG
|
||||
import DebugBridgeCore
|
||||
StateServer.shared.start()
|
||||
#if canImport(UIKit)
|
||||
import DebugBridgeUI
|
||||
// Install resolvers before StateServer opens its listener.
|
||||
DebugBridgeUIWiring.installAll()
|
||||
#endif
|
||||
// Replace AppState/AppStateAccessor with the type discovered in Phase 1.
|
||||
DebugBridgeManager.shared.start(
|
||||
appState: appState,
|
||||
register: AppStateAccessor.register
|
||||
)
|
||||
#endif
|
||||
```
|
||||
3. Build + deploy to the device with `xcodebuild -scheme <SchemeName>
|
||||
4. Build + deploy to the device with `xcodebuild -scheme <SchemeName>
|
||||
-destination 'platform=iOS,id=<UDID>' build install`.
|
||||
4. Launch via `devicectl device process launch --device <UDID> --console <bundle-id>`.
|
||||
5. Launch via `devicectl device process launch --device <UDID> --console <bundle-id>`.
|
||||
Capture the boot token printed to `os_log` on first run.
|
||||
5. Spawn the Mac-side daemon (on-demand) — `gstack-ios-qa-daemon`. Daemon
|
||||
6. Spawn the Mac-side daemon (on-demand) — `gstack-ios-qa-daemon`. Daemon
|
||||
acquires an exclusive flock on `~/.gstack/ios-qa-daemon.pid`. If another
|
||||
daemon is alive, the second invocation discovers its port and connects.
|
||||
6. Daemon immediately calls `POST /auth/rotate` on the iOS StateServer with a
|
||||
7. Daemon immediately calls `POST /auth/rotate` on the iOS StateServer with a
|
||||
fresh in-memory-only token. The boot token becomes useless ~5s later.
|
||||
Anything scraping `os_log` past this point sees a dead credential.
|
||||
If a fresh daemon finds the app running after another daemon consumed that
|
||||
one-use token, it verifies the bundle owner, relaunches the target once,
|
||||
waits for the new token, verifies ownership again, and then rotates.
|
||||
|
||||
## Phase 3: Vision-driven agent loop
|
||||
|
||||
@@ -145,7 +169,7 @@ Each iteration:
|
||||
|
||||
1. `GET /screenshot` (via daemon) → save PNG.
|
||||
2. `GET /elements` → accessibility tree.
|
||||
3. `GET /state/snapshot` (only `@Snapshotable` fields) → current state.
|
||||
3. `GET /state/snapshot` (only `// @Snapshotable` fields) → current state.
|
||||
4. Decide next action based on what's on the screen vs the test goal.
|
||||
5. `POST /session/acquire` to grab the device lock.
|
||||
6. Execute `POST /tap`, `/swipe`, `/type`, or `POST /state/<key>` write.
|
||||
@@ -209,7 +233,7 @@ live.
|
||||
| `curl: connection refused` to daemon | daemon crashed | Re-run `/ios-qa`; spawn-race lock will fail closed |
|
||||
| `403 identity_not_allowed` from `/auth/mint` | identity missing from allowlist | Run `gstack-ios-qa-mint --remote <identity>` on the Mac |
|
||||
| `409 schema_mismatch` on `/state/restore` | snapshot from older app build | Discard the snapshot; re-capture |
|
||||
| `503 device_disconnected` from proxy | USB tunnel dropped | Reconnect device; daemon auto-reconnects within 30s |
|
||||
| `503 device_disconnected` from proxy | USB route dropped or app relaunched | Daemon invalidates the stale tunnel and retries one fresh bootstrap; reconnect/unlock the iPhone if it persists |
|
||||
| `429 rate_limited` from `/auth/mint` | >10 mints/min from one identity | Wait 60s; check audit log for anomalies |
|
||||
| `413 body_too_large` on `/state/restore` | snapshot >1MB | Increase `--max-body` or trim snapshot |
|
||||
|
||||
|
||||
@@ -13,7 +13,10 @@ export interface DeviceEntry {
|
||||
identifier: string;
|
||||
name: string;
|
||||
model: string;
|
||||
platform: string; // "iOS" | "iPadOS" | "visionOS" | ...
|
||||
deviceType: string; // "iPhone" | "iPad" | "realityDevice" | ...
|
||||
state: string; // "connected" | "available" | "available (paired)" | ...
|
||||
transport: string; // "wired" on USB devices; empty for stale/unavailable entries
|
||||
paired: boolean;
|
||||
}
|
||||
|
||||
@@ -83,7 +86,10 @@ export function listDevices(spawn: SpawnImpl = defaultSpawn): DeviceEntry[] {
|
||||
identifier: String(d.identifier ?? ''),
|
||||
name: String(props?.name ?? 'unknown'),
|
||||
model: String(hw?.productType ?? 'unknown'),
|
||||
platform: String(hw?.platform ?? ''),
|
||||
deviceType: String(hw?.deviceType ?? ''),
|
||||
state: String(conn?.tunnelState ?? 'unknown'),
|
||||
transport: String(conn?.transportType ?? ''),
|
||||
paired: pairingState === 'paired',
|
||||
};
|
||||
});
|
||||
|
||||
+157
-27
@@ -62,16 +62,36 @@ export async function startDaemon(opts: DaemonOptions): Promise<RunningDaemon |
|
||||
|
||||
const tokenStore = new SessionTokenStore();
|
||||
let tunnel: DeviceTunnel | null = null;
|
||||
let cachedTunnelAt = 0;
|
||||
let tunnelInFlight: Promise<DeviceTunnel | null> | null = null;
|
||||
|
||||
const getTunnel = async (): Promise<DeviceTunnel | null> => {
|
||||
// Cache the tunnel for 30s; refresh on demand.
|
||||
if (tunnel && Date.now() - cachedTunnelAt < 30_000) return tunnel;
|
||||
if (opts.tunnelProvider) {
|
||||
tunnel = await opts.tunnelProvider();
|
||||
cachedTunnelAt = Date.now();
|
||||
// A successful bootstrap consumes and deletes the app's one-shot boot
|
||||
// token. Keep that rotated tunnel for this daemon's lifetime instead of
|
||||
// trying to bootstrap it again on a timer. Failed attempts are not cached.
|
||||
if (tunnel) return tunnel;
|
||||
if (!opts.tunnelProvider) return null;
|
||||
|
||||
// Multiple first requests can arrive before bootstrap completes. Share
|
||||
// one provider call so they cannot race through independent rotations.
|
||||
if (!tunnelInFlight) {
|
||||
tunnelInFlight = Promise.resolve()
|
||||
.then(() => opts.tunnelProvider!())
|
||||
.then((candidate) => {
|
||||
if (candidate) tunnel = candidate;
|
||||
return candidate;
|
||||
})
|
||||
.finally(() => {
|
||||
tunnelInFlight = null;
|
||||
});
|
||||
}
|
||||
return tunnel;
|
||||
return tunnelInFlight;
|
||||
};
|
||||
|
||||
const invalidateTunnel = (failedTunnel: DeviceTunnel): void => {
|
||||
// A late response from the old app must not evict a tunnel that another
|
||||
// request has already refreshed. Object identity gives each bootstrap a
|
||||
// cheap generation token without exposing generation state elsewhere.
|
||||
if (tunnel === failedTunnel) tunnel = null;
|
||||
};
|
||||
|
||||
// 2. Tailnet probe (fail-closed).
|
||||
@@ -86,7 +106,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<RunningDaemon |
|
||||
|
||||
// 3. Loopback listener (full surface).
|
||||
const loopbackServer = createServer(async (req, res) => {
|
||||
await handleLoopback({ req, res, tokenStore, getTunnel });
|
||||
await handleLoopback({ req, res, tokenStore, getTunnel, invalidateTunnel });
|
||||
});
|
||||
// Use port 0 for OS-assigned port when test/random port collisions are a risk.
|
||||
const requestedPort = opts.loopbackPort;
|
||||
@@ -97,7 +117,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<RunningDaemon |
|
||||
// mode this can collide; we try the actualPort first and skip ipv6 if it
|
||||
// fails (tests don't exercise ::1 explicitly).
|
||||
const loopbackServerV6 = createServer(async (req, res) => {
|
||||
await handleLoopback({ req, res, tokenStore, getTunnel });
|
||||
await handleLoopback({ req, res, tokenStore, getTunnel, invalidateTunnel });
|
||||
});
|
||||
let v6Bound = false;
|
||||
try {
|
||||
@@ -118,6 +138,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<RunningDaemon |
|
||||
res,
|
||||
tokenStore,
|
||||
getTunnel,
|
||||
invalidateTunnel,
|
||||
auditPath: opts.auditPath,
|
||||
attemptsPath: opts.attemptsPath,
|
||||
allowlistPath: opts.allowlistPath,
|
||||
@@ -181,12 +202,113 @@ interface HandlerCtx {
|
||||
res: ServerResponse;
|
||||
tokenStore: SessionTokenStore;
|
||||
getTunnel: () => Promise<DeviceTunnel | null>;
|
||||
invalidateTunnel: (failedTunnel: DeviceTunnel) => void;
|
||||
// Explicit security-log + allowlist paths (default to env-derived when undefined).
|
||||
auditPath?: string;
|
||||
attemptsPath?: string;
|
||||
allowlistPath?: string;
|
||||
}
|
||||
|
||||
type DeviceProxyResponse = Awaited<ReturnType<typeof proxyToDevice>>;
|
||||
const RECOVERABLE_SOCKET_ERRORS = new Set([
|
||||
'ECONNABORTED',
|
||||
'ECONNREFUSED',
|
||||
'ECONNRESET',
|
||||
'EHOSTUNREACH',
|
||||
'ENETUNREACH',
|
||||
'EPIPE',
|
||||
'ETIMEDOUT',
|
||||
]);
|
||||
|
||||
function localProxyError(status: number, error: string): DeviceProxyResponse {
|
||||
const body = Buffer.from(JSON.stringify({ error }, sanitizeReplacer));
|
||||
return {
|
||||
status,
|
||||
headers: { 'content-type': 'application/json', 'content-length': String(body.length) },
|
||||
body,
|
||||
};
|
||||
}
|
||||
|
||||
async function proxyAttempt(opts: Parameters<typeof proxyToDevice>[0]): Promise<DeviceProxyResponse> {
|
||||
try {
|
||||
return await proxyToDevice(opts);
|
||||
} catch (err) {
|
||||
const code = (err as { code?: string }).code;
|
||||
// CoreDevice can surface the same stale route as several different socket
|
||||
// failures while an app is being relaunched or replaced. Normalize those
|
||||
// failures so the cache recovery path below can handle all of them.
|
||||
if (code && RECOVERABLE_SOCKET_ERRORS.has(code)) {
|
||||
return localProxyError(503, 'device_disconnected');
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
function shouldRefreshTunnel(upstream: DeviceProxyResponse): boolean {
|
||||
// A relaunched app has a new in-memory bearer and rejects the daemon's old
|
||||
// rotated token. A redeploy can instead leave the old CoreDevice route
|
||||
// refusing connections or timing out. Both cases require a fresh bootstrap.
|
||||
if (upstream.status === 401) return true;
|
||||
if (upstream.status !== 503 && upstream.status !== 504) return false;
|
||||
try {
|
||||
const body = JSON.parse(upstream.body.toString('utf-8')) as { error?: string };
|
||||
return body.error === 'device_disconnected' || body.error === 'upstream_timeout';
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function canReplayAfterRefresh(inbound: IncomingMessage, upstream: DeviceProxyResponse): boolean {
|
||||
// A 401 proves the stale bearer was rejected before StateServer dispatched
|
||||
// the operation, so retrying is safe even for a mutation. Connection loss
|
||||
// is ambiguous: the app may have applied a tap/write before its response was
|
||||
// lost. Replay only read-only requests in that case to prevent double taps.
|
||||
if (upstream.status === 401) return true;
|
||||
const method = inbound.method ?? 'GET';
|
||||
return method === 'GET' || method === 'HEAD' || method === 'OPTIONS';
|
||||
}
|
||||
|
||||
async function proxyWithTunnelRecovery(opts: {
|
||||
inbound: IncomingMessage;
|
||||
body: Buffer;
|
||||
sessionId: string | null;
|
||||
agentIdentity?: string;
|
||||
getTunnel: HandlerCtx['getTunnel'];
|
||||
invalidateTunnel: HandlerCtx['invalidateTunnel'];
|
||||
}): Promise<{ tunnel: DeviceTunnel; upstream: DeviceProxyResponse } | null> {
|
||||
let tunnel = await opts.getTunnel();
|
||||
if (!tunnel) return null;
|
||||
|
||||
const makeAttempt = (candidate: DeviceTunnel) => proxyAttempt({
|
||||
inbound: opts.inbound,
|
||||
body: opts.body,
|
||||
tunnel: candidate,
|
||||
sessionId: opts.sessionId,
|
||||
agentIdentity: opts.agentIdentity,
|
||||
});
|
||||
|
||||
let upstream = await makeAttempt(tunnel);
|
||||
if (!shouldRefreshTunnel(upstream)) return { tunnel, upstream };
|
||||
|
||||
const failedTunnel = tunnel;
|
||||
const replaySafe = canReplayAfterRefresh(opts.inbound, upstream);
|
||||
opts.invalidateTunnel(tunnel);
|
||||
const refreshed = await opts.getTunnel();
|
||||
if (!refreshed) return replaySafe ? null : { tunnel: failedTunnel, upstream };
|
||||
|
||||
// The replacement is now cached for the next request, but never replay an
|
||||
// ambiguous mutation whose response was lost: doing so could double-tap or
|
||||
// apply a state transition twice.
|
||||
if (!replaySafe) return { tunnel: failedTunnel, upstream };
|
||||
|
||||
tunnel = refreshed;
|
||||
upstream = await makeAttempt(tunnel);
|
||||
// Do not loop forever if the replacement app is itself unavailable. Leave
|
||||
// the cache empty so the next independent request can bootstrap again.
|
||||
if (shouldRefreshTunnel(upstream)) opts.invalidateTunnel(tunnel);
|
||||
return { tunnel, upstream };
|
||||
}
|
||||
|
||||
function readBody(req: IncomingMessage, maxBytes = 1_048_576): Promise<Buffer | { error: 'body_too_large' }> {
|
||||
return new Promise((resolve, reject) => {
|
||||
const chunks: Buffer[] = [];
|
||||
@@ -228,7 +350,7 @@ function sendJson(res: ServerResponse, status: number, body: unknown): void {
|
||||
* loopback bind itself is the boundary).
|
||||
*/
|
||||
async function handleLoopback(ctx: HandlerCtx): Promise<void> {
|
||||
const { req, res, tokenStore, getTunnel } = ctx;
|
||||
const { req, res, tokenStore, getTunnel, invalidateTunnel } = ctx;
|
||||
const url = parseUrl(req.url ?? '/');
|
||||
const path = url.pathname ?? '/';
|
||||
const method = req.method ?? 'GET';
|
||||
@@ -262,16 +384,23 @@ async function handleLoopback(ctx: HandlerCtx): Promise<void> {
|
||||
}
|
||||
|
||||
// Other endpoints — proxy to the device.
|
||||
const tunnel = await getTunnel();
|
||||
if (!tunnel) {
|
||||
sendJson(res, 503, { error: 'device_not_connected' });
|
||||
return;
|
||||
}
|
||||
const body = await readBody(req);
|
||||
if ('error' in body) { sendJson(res, 413, body); return; }
|
||||
const sessionId = (req.headers['x-session-id'] as string | undefined) ?? null;
|
||||
const agentIdentity = (req.headers['x-agent-identity'] as string | undefined) ?? undefined;
|
||||
const upstream = await proxyToDevice({ inbound: req, body, tunnel, sessionId, agentIdentity });
|
||||
const proxied = await proxyWithTunnelRecovery({
|
||||
inbound: req,
|
||||
body,
|
||||
sessionId,
|
||||
agentIdentity,
|
||||
getTunnel,
|
||||
invalidateTunnel,
|
||||
});
|
||||
if (!proxied) {
|
||||
sendJson(res, 503, { error: 'device_not_connected' });
|
||||
return;
|
||||
}
|
||||
const { upstream } = proxied;
|
||||
res.writeHead(upstream.status, upstream.headers);
|
||||
res.end(upstream.body);
|
||||
} catch (err) {
|
||||
@@ -287,7 +416,7 @@ interface TailnetCtx extends HandlerCtx {
|
||||
* Tailnet handler — locked allowlist + capability tiers.
|
||||
*/
|
||||
async function handleTailnet(ctx: TailnetCtx): Promise<void> {
|
||||
const { req, res, tokenStore, getTunnel, whoIsImpl, auditPath, attemptsPath, allowlistPath } = ctx;
|
||||
const { req, res, tokenStore, getTunnel, invalidateTunnel, whoIsImpl, auditPath, attemptsPath, allowlistPath } = ctx;
|
||||
const url = parseUrl(req.url ?? '/');
|
||||
const path = url.pathname ?? '/';
|
||||
const method = req.method ?? 'GET';
|
||||
@@ -375,19 +504,20 @@ async function handleTailnet(ctx: TailnetCtx): Promise<void> {
|
||||
}
|
||||
|
||||
// Proxy to device.
|
||||
const tunnel = await getTunnel();
|
||||
if (!tunnel) {
|
||||
const sessionId = (req.headers['x-session-id'] as string | undefined) ?? null;
|
||||
const proxied = await proxyWithTunnelRecovery({
|
||||
inbound: req,
|
||||
body,
|
||||
sessionId,
|
||||
agentIdentity: session.identity,
|
||||
getTunnel,
|
||||
invalidateTunnel,
|
||||
});
|
||||
if (!proxied) {
|
||||
sendJson(res, 503, { error: 'device_not_connected' });
|
||||
return;
|
||||
}
|
||||
const sessionId = (req.headers['x-session-id'] as string | undefined) ?? null;
|
||||
const upstream = await proxyToDevice({
|
||||
inbound: req,
|
||||
body,
|
||||
tunnel,
|
||||
sessionId,
|
||||
agentIdentity: session.identity,
|
||||
});
|
||||
const { tunnel, upstream } = proxied;
|
||||
|
||||
// Audit the action (mutating endpoints only).
|
||||
if (requiredCapability !== 'observe') {
|
||||
|
||||
@@ -5,6 +5,8 @@
|
||||
// 2. launch the app on it (no-op if already running)
|
||||
// 3. wait briefly for the in-app StateServer to start
|
||||
// 4. copy the boot token from the app's sandbox via devicectl copy from
|
||||
// If an earlier daemon already consumed it, relaunch the app once to mint
|
||||
// a fresh boot token, then verify the relaunched StateServer again.
|
||||
// 5. POST /auth/rotate to swap boot token → fresh in-memory token
|
||||
// 6. return a DeviceTunnel pointing at the device's IPv6 with the rotated
|
||||
// bearer that subsequent proxied requests carry
|
||||
@@ -14,6 +16,7 @@
|
||||
// live token, which it scopes per-tailnet-session via /auth/mint.
|
||||
|
||||
import { randomBytes } from 'crypto';
|
||||
import { spawnSync } from 'child_process';
|
||||
import type { DeviceTunnel } from './proxy';
|
||||
import {
|
||||
listDevices,
|
||||
@@ -21,12 +24,13 @@ import {
|
||||
isAppRunning,
|
||||
launchApp,
|
||||
copyFileFromAppContainer,
|
||||
type DeviceEntry,
|
||||
type SpawnImpl,
|
||||
type ResolveImpl,
|
||||
} from './devicectl';
|
||||
|
||||
export interface BootstrapOptions {
|
||||
/** Target device UDID. If null, picks the first connected paired device. */
|
||||
/** Target iPhone UDID. If null, picks the best connected paired iPhone. */
|
||||
udid?: string;
|
||||
/** Bundle ID of the iOS app hosting the StateServer. */
|
||||
bundleId: string;
|
||||
@@ -53,10 +57,85 @@ export type BootstrapErrorReason =
|
||||
| 'launch_failed'
|
||||
| 'device_locked'
|
||||
| 'state_server_unreachable'
|
||||
| 'wrong_app'
|
||||
| 'boot_token_unavailable'
|
||||
| 'rotate_failed'
|
||||
| 'resolve_failed';
|
||||
|
||||
function isIPhoneDevice(device: DeviceEntry): boolean {
|
||||
const platform = device.platform.trim().toLowerCase();
|
||||
const deviceType = device.deviceType.trim().toLowerCase();
|
||||
const model = device.model.trim().toLowerCase();
|
||||
|
||||
// productType is present even on older CoreDevice versions. Prefer the
|
||||
// explicit platform/type fields when available, but retain productType as
|
||||
// a compatibility fallback. An explicit non-iOS platform always loses.
|
||||
if (platform && platform !== 'ios') return false;
|
||||
return deviceType === 'iphone' || model.startsWith('iphone');
|
||||
}
|
||||
|
||||
function isAvailableDevice(device: Pick<DeviceEntry, 'state' | 'transport'>): boolean {
|
||||
const state = device.state.trim().toLowerCase();
|
||||
const transport = device.transport.trim().toLowerCase();
|
||||
// Xcode 26.6 / iOS 27 beta can report a USB-reachable iPhone as
|
||||
// tunnelState=disconnected until the next devicectl command establishes
|
||||
// the CoreDevice tunnel. The wired transport is the authoritative signal
|
||||
// in that transitional state. Stale devices have no wired transport.
|
||||
return state === 'connected'
|
||||
|| state.startsWith('available')
|
||||
|| (state === 'disconnected' && transport === 'wired');
|
||||
}
|
||||
|
||||
function defaultDeviceRank(device: DeviceEntry): number {
|
||||
if (!device.paired || !isIPhoneDevice(device) || !isAvailableDevice(device)) return -1;
|
||||
|
||||
const state = device.state.trim().toLowerCase();
|
||||
const transport = device.transport.trim().toLowerCase();
|
||||
// Prefer the USB-connected phone the user is actively working with. Then
|
||||
// prefer an established CoreDevice tunnel over a merely available device.
|
||||
return (transport === 'wired' ? 100 : 0)
|
||||
+ (state === 'connected' ? 10 : 0)
|
||||
+ (state.startsWith('available') ? 1 : 0);
|
||||
}
|
||||
|
||||
function pickDefaultDevice(devices: DeviceEntry[]): DeviceEntry | undefined {
|
||||
let best: DeviceEntry | undefined;
|
||||
let bestRank = -1;
|
||||
for (const device of devices) {
|
||||
const rank = defaultDeviceRank(device);
|
||||
if (rank > bestRank) {
|
||||
best = device;
|
||||
bestRank = rank;
|
||||
}
|
||||
}
|
||||
return best;
|
||||
}
|
||||
|
||||
const defaultSpawn: SpawnImpl = (cmd, args) => spawnSync(cmd, args, {
|
||||
stdio: 'pipe',
|
||||
timeout: 60_000,
|
||||
});
|
||||
|
||||
function relaunchApp(
|
||||
udid: string,
|
||||
bundleId: string,
|
||||
spawn: SpawnImpl = defaultSpawn,
|
||||
): { ok: true } | { ok: false; error: 'device_locked' | 'launch_failed'; detail?: string } {
|
||||
const r = spawn('xcrun', [
|
||||
'devicectl', 'device', 'process', 'launch',
|
||||
'--device', udid,
|
||||
'--terminate-existing',
|
||||
bundleId,
|
||||
]);
|
||||
if (r.status === 0) return { ok: true };
|
||||
|
||||
const detail = `${r.stderr?.toString() ?? ''}${r.stdout?.toString() ?? ''}`.trim();
|
||||
if (detail.includes('was not, or could not be, unlocked')) {
|
||||
return { ok: false, error: 'device_locked', detail };
|
||||
}
|
||||
return { ok: false, error: 'launch_failed', detail };
|
||||
}
|
||||
|
||||
/**
|
||||
* Bootstrap a real CoreDevice tunnel to an iOS app's StateServer. Used by
|
||||
* the daemon's default tunnelProvider when GSTACK_IOS_TARGET_UDID is set
|
||||
@@ -77,9 +156,39 @@ export async function bootstrapTunnel(opts: BootstrapOptions): Promise<Bootstrap
|
||||
}
|
||||
const target = opts.udid
|
||||
? devices.find((d) => d.identifier === opts.udid)
|
||||
: devices.find((d) => d.paired) ?? devices[0];
|
||||
: pickDefaultDevice(devices);
|
||||
if (!target) {
|
||||
return { ok: false, error: 'device_not_found', detail: opts.udid };
|
||||
if (opts.udid) {
|
||||
return { ok: false, error: 'device_not_found', detail: opts.udid };
|
||||
}
|
||||
const pairedIPhone = devices.find((d) => d.paired && isIPhoneDevice(d));
|
||||
if (pairedIPhone) {
|
||||
return {
|
||||
ok: false,
|
||||
error: 'device_not_found',
|
||||
detail: `paired iPhone ${pairedIPhone.name} (${pairedIPhone.identifier}) is ${pairedIPhone.state}; connect it over USB and unlock it`,
|
||||
};
|
||||
}
|
||||
const firstIPhone = devices.find(isIPhoneDevice);
|
||||
if (!firstIPhone) {
|
||||
return {
|
||||
ok: false,
|
||||
error: 'device_not_found',
|
||||
detail: 'no iPhone is connected; non-iOS devices are not eligible for iOS QA',
|
||||
};
|
||||
}
|
||||
return {
|
||||
ok: false,
|
||||
error: 'no_paired_device',
|
||||
detail: `device ${firstIPhone.name} (${firstIPhone.identifier}) is ${firstIPhone.state}; run \`xcrun devicectl manage pair --device ${firstIPhone.identifier}\` and tap Trust on the iPhone`,
|
||||
};
|
||||
}
|
||||
if (!isIPhoneDevice(target)) {
|
||||
return {
|
||||
ok: false,
|
||||
error: 'device_not_found',
|
||||
detail: `device ${target.name} (${target.identifier}) is ${target.platform || target.model}, not an iPhone`,
|
||||
};
|
||||
}
|
||||
if (!target.paired) {
|
||||
return {
|
||||
@@ -88,6 +197,13 @@ export async function bootstrapTunnel(opts: BootstrapOptions): Promise<Bootstrap
|
||||
detail: `device ${target.name} (${target.identifier}) is ${target.state}; run \`xcrun devicectl manage pair --device ${target.identifier}\` and tap Trust on the iPhone`,
|
||||
};
|
||||
}
|
||||
if (!isAvailableDevice(target)) {
|
||||
return {
|
||||
ok: false,
|
||||
error: 'device_not_found',
|
||||
detail: `device ${target.name} (${target.identifier}) is ${target.state}; connect it over USB and unlock it`,
|
||||
};
|
||||
}
|
||||
|
||||
// Step 2: launch app (idempotent — devicectl returns success if already running)
|
||||
if (!isAppRunning(target.identifier, opts.bundleId, spawn)) {
|
||||
@@ -118,29 +234,77 @@ export async function bootstrapTunnel(opts: BootstrapOptions): Promise<Bootstrap
|
||||
|
||||
// Step 4: wait for StateServer to become reachable, then scrape boot token.
|
||||
// Probe /healthz with retries (the listener can take a moment to bind).
|
||||
const deadline = Date.now() + startupTimeoutMs;
|
||||
let healthOK = false;
|
||||
while (Date.now() < deadline) {
|
||||
try {
|
||||
const r = await fetchFn(`http://[${ipv6}]:${port}/healthz`, {
|
||||
signal: AbortSignal.timeout(2_000),
|
||||
});
|
||||
if (r.ok) { healthOK = true; break; }
|
||||
} catch { /* retry */ }
|
||||
await new Promise((res) => setTimeout(res, 250));
|
||||
}
|
||||
if (!healthOK) {
|
||||
return { ok: false, error: 'state_server_unreachable', detail: `no /healthz response from [${ipv6}]:${port} within ${startupTimeoutMs}ms` };
|
||||
}
|
||||
const waitForStateServer = async (): Promise<BootstrapResult | null> => {
|
||||
const deadline = Date.now() + startupTimeoutMs;
|
||||
while (Date.now() < deadline) {
|
||||
try {
|
||||
const r = await fetchFn(`http://[${ipv6}]:${port}/healthz`, {
|
||||
signal: AbortSignal.timeout(2_000),
|
||||
});
|
||||
if (r.ok) {
|
||||
const health = await r.json().catch(() => null) as { bundle_id?: string } | null;
|
||||
// Older bridges did not identify their bundle. Preserve compatibility,
|
||||
// but reject an explicit mismatch from current bridges: another debug
|
||||
// app already owns the fixed StateServer port on this device.
|
||||
if (health?.bundle_id && health.bundle_id !== opts.bundleId) {
|
||||
return {
|
||||
ok: false,
|
||||
error: 'wrong_app',
|
||||
detail: `expected ${opts.bundleId} but StateServer port ${port} belongs to ${health.bundle_id}; terminate the other debug app`,
|
||||
};
|
||||
}
|
||||
return null;
|
||||
}
|
||||
} catch { /* retry */ }
|
||||
await new Promise((res) => setTimeout(res, 250));
|
||||
}
|
||||
return {
|
||||
ok: false,
|
||||
error: 'state_server_unreachable',
|
||||
detail: `no /healthz response from [${ipv6}]:${port} within ${startupTimeoutMs}ms`,
|
||||
};
|
||||
};
|
||||
|
||||
const bootToken = copyFileFromAppContainer({
|
||||
const healthFailure = await waitForStateServer();
|
||||
if (healthFailure) return healthFailure;
|
||||
|
||||
const readBootToken = () => copyFileFromAppContainer({
|
||||
udid: target.identifier,
|
||||
bundleId: opts.bundleId,
|
||||
sourceRelativePath: tokenPath,
|
||||
spawn,
|
||||
});
|
||||
|
||||
let bootToken = readBootToken();
|
||||
if (!bootToken) {
|
||||
return { ok: false, error: 'boot_token_unavailable', detail: `couldn't read ${tokenPath} from ${opts.bundleId}` };
|
||||
// A healthy running app can lack a boot token when an earlier daemon
|
||||
// already rotated it. A new daemon has no way to recover that in-memory
|
||||
// bearer, so restart exactly once to make StateServer mint a fresh one.
|
||||
// The explicit bundle check above prevents disrupting an unrelated app
|
||||
// that happens to own the fixed StateServer port.
|
||||
const relaunched = relaunchApp(target.identifier, opts.bundleId, spawn);
|
||||
if (!relaunched.ok) {
|
||||
return { ok: false, error: relaunched.error, detail: relaunched.detail };
|
||||
}
|
||||
|
||||
// The token is written before StateServer opens its listener. Waiting for
|
||||
// it first prevents a stale response from the terminating process from
|
||||
// being mistaken for readiness of the replacement process.
|
||||
const tokenDeadline = Date.now() + startupTimeoutMs;
|
||||
while (!bootToken && Date.now() < tokenDeadline) {
|
||||
bootToken = readBootToken();
|
||||
if (!bootToken) await new Promise((res) => setTimeout(res, 250));
|
||||
}
|
||||
if (!bootToken) {
|
||||
return {
|
||||
ok: false,
|
||||
error: 'boot_token_unavailable',
|
||||
detail: `couldn't read ${tokenPath} from ${opts.bundleId} after relaunch`,
|
||||
};
|
||||
}
|
||||
|
||||
const relaunchedHealthFailure = await waitForStateServer();
|
||||
if (relaunchedHealthFailure) return relaunchedHealthFailure;
|
||||
}
|
||||
|
||||
// Step 5: rotate the boot token to a fresh in-memory-only one.
|
||||
|
||||
@@ -132,6 +132,258 @@ describe('daemon — loopback listener', () => {
|
||||
expect(lastReq?.headers['x-session-id']).toBe('sess-loopback-1');
|
||||
});
|
||||
|
||||
test('concurrent first requests share one tunnel bootstrap', async () => {
|
||||
let bootstraps = 0;
|
||||
let releaseBootstrap!: () => void;
|
||||
let markBootstrapStarted!: () => void;
|
||||
const bootstrapStarted = new Promise<void>((resolve) => { markBootstrapStarted = resolve; });
|
||||
const bootstrapGate = new Promise<void>((resolve) => { releaseBootstrap = resolve; });
|
||||
const tunnel: DeviceTunnel = {
|
||||
udid: 'STUB-UDID',
|
||||
ipv6Addr: '127.0.0.1',
|
||||
port: stub.port,
|
||||
bootTokenRotated: STATE_SERVER_TOKEN,
|
||||
};
|
||||
const d = await startDaemon({
|
||||
loopbackPort: 0,
|
||||
tailnetEnabled: false,
|
||||
pidfilePath: join(workDir, 'daemon-concurrent-bootstrap.pid'),
|
||||
tunnelProvider: async () => {
|
||||
bootstraps++;
|
||||
markBootstrapStarted();
|
||||
await bootstrapGate;
|
||||
return tunnel;
|
||||
},
|
||||
});
|
||||
if ('error' in d) throw new Error(d.error);
|
||||
|
||||
try {
|
||||
const base = `http://127.0.0.1:${d.loopbackPort}`;
|
||||
const requests = [
|
||||
fetchWith('GET', `${base}/screenshot`),
|
||||
fetchWith('GET', `${base}/screenshot`),
|
||||
fetchWith('GET', `${base}/screenshot`),
|
||||
];
|
||||
await bootstrapStarted;
|
||||
await new Promise((resolve) => setTimeout(resolve, 25));
|
||||
releaseBootstrap();
|
||||
const responses = await Promise.all(requests);
|
||||
expect(responses.map((response) => response.status)).toEqual([200, 200, 200]);
|
||||
expect(bootstraps).toBe(1);
|
||||
} finally {
|
||||
releaseBootstrap();
|
||||
await d.close();
|
||||
}
|
||||
});
|
||||
|
||||
test('reuses a healthy rotated tunnel beyond the old 30-second boundary', async () => {
|
||||
let bootstraps = 0;
|
||||
const tunnel: DeviceTunnel = {
|
||||
udid: 'STUB-UDID',
|
||||
ipv6Addr: '127.0.0.1',
|
||||
port: stub.port,
|
||||
bootTokenRotated: STATE_SERVER_TOKEN,
|
||||
};
|
||||
const d = await startDaemon({
|
||||
loopbackPort: 0,
|
||||
tailnetEnabled: false,
|
||||
pidfilePath: join(workDir, 'daemon-one-shot-bootstrap.pid'),
|
||||
tunnelProvider: async () => {
|
||||
bootstraps++;
|
||||
if (bootstraps > 1) throw new Error('one-shot boot token was already consumed');
|
||||
return tunnel;
|
||||
},
|
||||
});
|
||||
if ('error' in d) throw new Error(d.error);
|
||||
|
||||
const realNow = Date.now;
|
||||
const firstRequestAt = realNow();
|
||||
try {
|
||||
const base = `http://127.0.0.1:${d.loopbackPort}`;
|
||||
const first = await fetchWith('GET', `${base}/screenshot`);
|
||||
expect(first.status).toBe(200);
|
||||
|
||||
Date.now = () => firstRequestAt + 30_001;
|
||||
const later = await fetchWith('GET', `${base}/screenshot`);
|
||||
expect(later.status).toBe(200);
|
||||
expect(bootstraps).toBe(1);
|
||||
} finally {
|
||||
Date.now = realNow;
|
||||
await d.close();
|
||||
}
|
||||
});
|
||||
|
||||
test('401 after app relaunch invalidates the token and concurrent requests share one rebootstrap', async () => {
|
||||
let bootstraps = 0;
|
||||
let markRefreshStarted!: () => void;
|
||||
let releaseRefresh!: () => void;
|
||||
const refreshStarted = new Promise<void>((resolve) => { markRefreshStarted = resolve; });
|
||||
const refreshGate = new Promise<void>((resolve) => { releaseRefresh = resolve; });
|
||||
const staleTunnel: DeviceTunnel = {
|
||||
udid: 'STUB-UDID',
|
||||
ipv6Addr: '127.0.0.1',
|
||||
port: stub.port,
|
||||
bootTokenRotated: 'expired-after-relaunch',
|
||||
};
|
||||
const refreshedTunnel: DeviceTunnel = {
|
||||
...staleTunnel,
|
||||
bootTokenRotated: STATE_SERVER_TOKEN,
|
||||
};
|
||||
const d = await startDaemon({
|
||||
loopbackPort: 0,
|
||||
tailnetEnabled: false,
|
||||
pidfilePath: join(workDir, 'daemon-relaunch-refresh.pid'),
|
||||
tunnelProvider: async () => {
|
||||
bootstraps++;
|
||||
if (bootstraps === 1) return staleTunnel;
|
||||
if (bootstraps === 2) {
|
||||
markRefreshStarted();
|
||||
await refreshGate;
|
||||
return refreshedTunnel;
|
||||
}
|
||||
throw new Error('concurrent 401s caused duplicate bootstraps');
|
||||
},
|
||||
});
|
||||
if ('error' in d) throw new Error(d.error);
|
||||
|
||||
const requestStart = stub.receivedRequests.length;
|
||||
try {
|
||||
const base = `http://127.0.0.1:${d.loopbackPort}`;
|
||||
const requests = [
|
||||
fetchWith('GET', `${base}/screenshot`),
|
||||
fetchWith('GET', `${base}/screenshot`),
|
||||
fetchWith('GET', `${base}/screenshot`),
|
||||
];
|
||||
await refreshStarted;
|
||||
await new Promise((resolve) => setTimeout(resolve, 25));
|
||||
expect(bootstraps).toBe(2);
|
||||
releaseRefresh();
|
||||
|
||||
const responses = await Promise.all(requests);
|
||||
expect(responses.map((response) => response.status)).toEqual([200, 200, 200]);
|
||||
const attempts = stub.receivedRequests.slice(requestStart);
|
||||
expect(attempts.filter((request) => request.headers.authorization === 'Bearer expired-after-relaunch')).toHaveLength(3);
|
||||
expect(attempts.filter((request) => request.headers.authorization === `Bearer ${STATE_SERVER_TOKEN}`)).toHaveLength(3);
|
||||
|
||||
const healthyReuse = await fetchWith('GET', `${base}/screenshot`);
|
||||
expect(healthyReuse.status).toBe(200);
|
||||
expect(bootstraps).toBe(2);
|
||||
} finally {
|
||||
releaseRefresh();
|
||||
await d.close();
|
||||
}
|
||||
});
|
||||
|
||||
test('connection failure after redeploy reboots the tunnel once and keeps the replacement cached', async () => {
|
||||
const deadPort = await new Promise<number>((resolve, reject) => {
|
||||
const reservation = createServer();
|
||||
reservation.once('error', reject);
|
||||
reservation.listen(0, '127.0.0.1', () => {
|
||||
const address = reservation.address();
|
||||
const port = typeof address === 'object' && address ? address.port : 0;
|
||||
reservation.close((err) => err ? reject(err) : resolve(port));
|
||||
});
|
||||
});
|
||||
let bootstraps = 0;
|
||||
const d = await startDaemon({
|
||||
loopbackPort: 0,
|
||||
tailnetEnabled: false,
|
||||
pidfilePath: join(workDir, 'daemon-redeploy-refresh.pid'),
|
||||
tunnelProvider: async () => {
|
||||
bootstraps++;
|
||||
if (bootstraps === 1) {
|
||||
return {
|
||||
udid: 'STUB-UDID',
|
||||
ipv6Addr: '127.0.0.1',
|
||||
port: deadPort,
|
||||
bootTokenRotated: 'old-deploy-token',
|
||||
};
|
||||
}
|
||||
if (bootstraps === 2) {
|
||||
return {
|
||||
udid: 'STUB-UDID',
|
||||
ipv6Addr: '127.0.0.1',
|
||||
port: stub.port,
|
||||
bootTokenRotated: STATE_SERVER_TOKEN,
|
||||
};
|
||||
}
|
||||
throw new Error('healthy replacement tunnel was not reused');
|
||||
},
|
||||
});
|
||||
if ('error' in d) throw new Error(d.error);
|
||||
|
||||
try {
|
||||
const base = `http://127.0.0.1:${d.loopbackPort}`;
|
||||
const recovered = await fetchWith('GET', `${base}/screenshot`);
|
||||
expect(recovered.status).toBe(200);
|
||||
expect(JSON.parse(recovered.bodyText)).toEqual({ png_base64: 'abc=' });
|
||||
expect(bootstraps).toBe(2);
|
||||
|
||||
const healthyReuse = await fetchWith('GET', `${base}/screenshot`);
|
||||
expect(healthyReuse.status).toBe(200);
|
||||
expect(bootstraps).toBe(2);
|
||||
} finally {
|
||||
await d.close();
|
||||
}
|
||||
});
|
||||
|
||||
test('connection failure refreshes but never replays an ambiguous tap', async () => {
|
||||
const deadPort = await new Promise<number>((resolve, reject) => {
|
||||
const reservation = createServer();
|
||||
reservation.once('error', reject);
|
||||
reservation.listen(0, '127.0.0.1', () => {
|
||||
const address = reservation.address();
|
||||
const port = typeof address === 'object' && address ? address.port : 0;
|
||||
reservation.close((err) => err ? reject(err) : resolve(port));
|
||||
});
|
||||
});
|
||||
let bootstraps = 0;
|
||||
const d = await startDaemon({
|
||||
loopbackPort: 0,
|
||||
tailnetEnabled: false,
|
||||
pidfilePath: join(workDir, 'daemon-mutation-no-replay.pid'),
|
||||
tunnelProvider: async () => {
|
||||
bootstraps++;
|
||||
return bootstraps === 1
|
||||
? {
|
||||
udid: 'STUB-UDID',
|
||||
ipv6Addr: '127.0.0.1',
|
||||
port: deadPort,
|
||||
bootTokenRotated: 'old-deploy-token',
|
||||
}
|
||||
: {
|
||||
udid: 'STUB-UDID',
|
||||
ipv6Addr: '127.0.0.1',
|
||||
port: stub.port,
|
||||
bootTokenRotated: STATE_SERVER_TOKEN,
|
||||
};
|
||||
},
|
||||
});
|
||||
if ('error' in d) throw new Error(d.error);
|
||||
|
||||
const beforeTaps = stub.receivedRequests.filter((request) => request.path === '/tap').length;
|
||||
try {
|
||||
const base = `http://127.0.0.1:${d.loopbackPort}`;
|
||||
const ambiguous = await fetchWith('POST', `${base}/tap`, {
|
||||
headers: { 'x-session-id': 'old-session', 'content-type': 'application/json' },
|
||||
body: JSON.stringify({ x: 10, y: 20 }),
|
||||
});
|
||||
expect(ambiguous.status).toBe(503);
|
||||
expect(bootstraps).toBe(2);
|
||||
expect(stub.receivedRequests.filter((request) => request.path === '/tap')).toHaveLength(beforeTaps);
|
||||
|
||||
const explicitRetry = await fetchWith('POST', `${base}/tap`, {
|
||||
headers: { 'x-session-id': 'new-session', 'content-type': 'application/json' },
|
||||
body: JSON.stringify({ x: 10, y: 20 }),
|
||||
});
|
||||
expect(explicitRetry.status).toBe(200);
|
||||
expect(stub.receivedRequests.filter((request) => request.path === '/tap')).toHaveLength(beforeTaps + 1);
|
||||
expect(bootstraps).toBe(2);
|
||||
} finally {
|
||||
await d.close();
|
||||
}
|
||||
});
|
||||
|
||||
test('returns 503 when no device tunnel is provided', async () => {
|
||||
// Force tunnel provider to return null by closing + restarting with null provider.
|
||||
await daemon.close();
|
||||
|
||||
@@ -105,6 +105,219 @@ describe('bootstrapTunnel', () => {
|
||||
}
|
||||
});
|
||||
|
||||
test('never auto-selects a connected paired Vision Pro ahead of an iPhone', async () => {
|
||||
const spawn = makeSpawn([
|
||||
{
|
||||
argsMatch: /devicectl list devices/,
|
||||
jsonOutput: {
|
||||
result: { devices: [
|
||||
{
|
||||
identifier: 'VISION',
|
||||
connectionProperties: { tunnelState: 'connected', pairingState: 'paired' },
|
||||
deviceProperties: { name: 'Vision Pro' },
|
||||
hardwareProperties: {
|
||||
productType: 'RealityDevice17,1',
|
||||
platform: 'visionOS',
|
||||
deviceType: 'realityDevice',
|
||||
},
|
||||
},
|
||||
{
|
||||
identifier: 'IPHONE',
|
||||
connectionProperties: { tunnelState: 'connected', pairingState: 'paired', transportType: 'wired' },
|
||||
deviceProperties: { name: 'USB iPhone' },
|
||||
hardwareProperties: {
|
||||
productType: 'iPhone17,1',
|
||||
platform: 'iOS',
|
||||
deviceType: 'iPhone',
|
||||
},
|
||||
},
|
||||
] },
|
||||
},
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device info processes -d IPHONE/,
|
||||
jsonOutput: { result: { runningProcesses: [{ executable: 'file:///var/containers/Bundle/Application/X/com.test.app/com.test' }] } },
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device info details --device IPHONE/,
|
||||
jsonOutput: { result: { connectionProperties: { tunnelIPAddress: 'fd00::17' } } },
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device copy from --device IPHONE/,
|
||||
destOutput: 'TOKEN\n',
|
||||
},
|
||||
]);
|
||||
|
||||
const r = await bootstrapTunnel({
|
||||
bundleId: 'com.test',
|
||||
spawnImpl: spawn,
|
||||
fetchImpl: (async () => new Response('{"ok":true}', { status: 200 })) as typeof fetch,
|
||||
});
|
||||
|
||||
expect(r.ok).toBe(true);
|
||||
if (r.ok) expect(r.tunnel.udid).toBe('IPHONE');
|
||||
});
|
||||
|
||||
test('fails clearly when only non-iPhone platforms are connected', async () => {
|
||||
const spawn = makeSpawn([
|
||||
{
|
||||
argsMatch: /devicectl list devices/,
|
||||
jsonOutput: {
|
||||
result: { devices: [
|
||||
{
|
||||
identifier: 'VISION',
|
||||
connectionProperties: { tunnelState: 'connected', pairingState: 'paired' },
|
||||
deviceProperties: { name: 'Vision Pro' },
|
||||
hardwareProperties: {
|
||||
productType: 'RealityDevice17,1',
|
||||
platform: 'visionOS',
|
||||
deviceType: 'realityDevice',
|
||||
},
|
||||
},
|
||||
{
|
||||
identifier: 'IPAD',
|
||||
connectionProperties: { tunnelState: 'connected', pairingState: 'paired' },
|
||||
deviceProperties: { name: 'iPad' },
|
||||
hardwareProperties: {
|
||||
productType: 'iPad16,6',
|
||||
platform: 'iOS',
|
||||
deviceType: 'iPad',
|
||||
},
|
||||
},
|
||||
] },
|
||||
},
|
||||
},
|
||||
]);
|
||||
|
||||
const r = await bootstrapTunnel({ bundleId: 'com.test', spawnImpl: spawn });
|
||||
expect(r.ok).toBe(false);
|
||||
if (!r.ok) {
|
||||
expect(r.error).toBe('device_not_found');
|
||||
expect(r.detail).toContain('no iPhone');
|
||||
}
|
||||
});
|
||||
|
||||
test('rejects an explicitly targeted non-iPhone device', async () => {
|
||||
const spawn = makeSpawn([
|
||||
{
|
||||
argsMatch: /devicectl list devices/,
|
||||
jsonOutput: {
|
||||
result: { devices: [{
|
||||
identifier: 'VISION',
|
||||
connectionProperties: { tunnelState: 'connected', pairingState: 'paired' },
|
||||
deviceProperties: { name: 'Vision Pro' },
|
||||
hardwareProperties: {
|
||||
productType: 'RealityDevice17,1',
|
||||
platform: 'visionOS',
|
||||
deviceType: 'realityDevice',
|
||||
},
|
||||
}] },
|
||||
},
|
||||
},
|
||||
]);
|
||||
|
||||
const r = await bootstrapTunnel({ bundleId: 'com.test', udid: 'VISION', spawnImpl: spawn });
|
||||
expect(r.ok).toBe(false);
|
||||
if (!r.ok) {
|
||||
expect(r.error).toBe('device_not_found');
|
||||
expect(r.detail).toContain('not an iPhone');
|
||||
}
|
||||
});
|
||||
|
||||
test('skips an unavailable paired device for a connected or available paired device', async () => {
|
||||
const spawn = makeSpawn([
|
||||
{
|
||||
argsMatch: /devicectl list devices/,
|
||||
jsonOutput: {
|
||||
result: { devices: [
|
||||
{
|
||||
identifier: 'STALE',
|
||||
connectionProperties: { tunnelState: 'unavailable', pairingState: 'paired' },
|
||||
deviceProperties: { name: 'Stale iPhone' },
|
||||
hardwareProperties: { productType: 'iPhone17,1' },
|
||||
},
|
||||
{
|
||||
identifier: 'WIRED',
|
||||
connectionProperties: { tunnelState: 'available', pairingState: 'paired', transportType: 'wired' },
|
||||
deviceProperties: { name: 'Wired iPhone' },
|
||||
hardwareProperties: { productType: 'iPhone18,2' },
|
||||
},
|
||||
] },
|
||||
},
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device info processes -d WIRED/,
|
||||
jsonOutput: { result: { runningProcesses: [{ executable: 'file:///var/containers/Bundle/Application/X/com.test.app/com.test' }] } },
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device info details --device WIRED/,
|
||||
jsonOutput: { result: { connectionProperties: { tunnelIPAddress: 'fd00::2' } } },
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device copy from --device WIRED/,
|
||||
destOutput: 'TOKEN\n',
|
||||
},
|
||||
]);
|
||||
|
||||
const r = await bootstrapTunnel({
|
||||
bundleId: 'com.test',
|
||||
spawnImpl: spawn,
|
||||
fetchImpl: (async () => new Response('{"ok":true}', { status: 200 })) as typeof fetch,
|
||||
});
|
||||
|
||||
expect(r.ok).toBe(true);
|
||||
if (r.ok) expect(r.tunnel.udid).toBe('WIRED');
|
||||
});
|
||||
|
||||
test('accepts a wired iPhone whose tunnel is disconnected until devicectl wakes it', async () => {
|
||||
const spawn = makeSpawn([
|
||||
{
|
||||
argsMatch: /devicectl list devices/,
|
||||
jsonOutput: {
|
||||
result: { devices: [
|
||||
{
|
||||
identifier: 'STALE-VISION',
|
||||
connectionProperties: { tunnelState: 'unavailable', pairingState: 'paired' },
|
||||
deviceProperties: { name: 'Stale Vision Pro' },
|
||||
hardwareProperties: { productType: 'RealityDevice14,1' },
|
||||
},
|
||||
{
|
||||
identifier: 'WIRED-DISCONNECTED',
|
||||
connectionProperties: {
|
||||
tunnelState: 'disconnected',
|
||||
pairingState: 'paired',
|
||||
transportType: 'wired',
|
||||
},
|
||||
deviceProperties: { name: 'USB iPhone' },
|
||||
hardwareProperties: { productType: 'iPhone18,2' },
|
||||
},
|
||||
] },
|
||||
},
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device info processes -d WIRED-DISCONNECTED/,
|
||||
jsonOutput: { result: { runningProcesses: [{ executable: 'file:\/\/\/var\/containers\/Bundle\/Application\/X\/com.test.app\/com.test' }] } },
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device info details --device WIRED-DISCONNECTED/,
|
||||
jsonOutput: { result: { connectionProperties: { tunnelIPAddress: 'fd00::27' } } },
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device copy from --device WIRED-DISCONNECTED/,
|
||||
destOutput: 'TOKEN\n',
|
||||
},
|
||||
]);
|
||||
|
||||
const r = await bootstrapTunnel({
|
||||
bundleId: 'com.test',
|
||||
spawnImpl: spawn,
|
||||
fetchImpl: (async () => new Response('{"ok":true}', { status: 200 })) as typeof fetch,
|
||||
});
|
||||
|
||||
expect(r.ok).toBe(true);
|
||||
if (r.ok) expect(r.tunnel.udid).toBe('WIRED-DISCONNECTED');
|
||||
});
|
||||
|
||||
test('returns device_locked when launchApp errors due to lock', async () => {
|
||||
const spawn = makeSpawn([
|
||||
{
|
||||
@@ -166,6 +379,48 @@ describe('bootstrapTunnel', () => {
|
||||
if (!r.ok) expect(r.error).toBe('state_server_unreachable');
|
||||
});
|
||||
|
||||
test('rejects a StateServer owned by a different app bundle', async () => {
|
||||
const spawn = makeSpawn([
|
||||
{
|
||||
argsMatch: /devicectl list devices/,
|
||||
jsonOutput: {
|
||||
result: { devices: [{
|
||||
identifier: 'TEST',
|
||||
connectionProperties: { tunnelState: 'connected', pairingState: 'paired' },
|
||||
deviceProperties: { name: 'Test' },
|
||||
hardwareProperties: { productType: 'iPhone18,2' },
|
||||
}] },
|
||||
},
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device info processes/,
|
||||
jsonOutput: { result: { runningProcesses: [] } },
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device process launch/,
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device info details/,
|
||||
jsonOutput: { result: { connectionProperties: { tunnelIPAddress: 'fd00::9' } } },
|
||||
},
|
||||
]);
|
||||
|
||||
const r = await bootstrapTunnel({
|
||||
bundleId: 'com.expected.app',
|
||||
spawnImpl: spawn,
|
||||
fetchImpl: (async () => new Response(
|
||||
JSON.stringify({ bundle_id: 'com.other.debug-app' }),
|
||||
{ status: 200, headers: { 'content-type': 'application/json' } },
|
||||
)) as typeof fetch,
|
||||
});
|
||||
|
||||
expect(r.ok).toBe(false);
|
||||
if (!r.ok) {
|
||||
expect(r.error).toBe('wrong_app');
|
||||
expect(r.detail).toContain('com.other.debug-app');
|
||||
}
|
||||
});
|
||||
|
||||
test('happy path: returns DeviceTunnel with rotated token', async () => {
|
||||
const spawn = makeSpawn([
|
||||
{
|
||||
@@ -234,6 +489,125 @@ describe('bootstrapTunnel', () => {
|
||||
expect(fetchCalls[fetchCalls.length - 1]?.url).toContain('/auth/rotate');
|
||||
});
|
||||
|
||||
test('relaunches once when a prior daemon consumed the running app boot token', async () => {
|
||||
const spawn = makeSpawn([
|
||||
{
|
||||
argsMatch: /devicectl list devices/,
|
||||
jsonOutput: {
|
||||
result: { devices: [{
|
||||
identifier: 'TEST-UDID',
|
||||
connectionProperties: { tunnelState: 'connected', pairingState: 'paired' },
|
||||
deviceProperties: { name: 'Test Device' },
|
||||
hardwareProperties: { productType: 'iPhone18,2' },
|
||||
}] },
|
||||
},
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device info processes/,
|
||||
jsonOutput: { result: { runningProcesses: [{ executable: 'file:\/\/\/var\/containers\/Bundle\/Application\/X\/com.test.app\/com.test' }] } },
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device info details/,
|
||||
jsonOutput: { result: { connectionProperties: { tunnelIPAddress: 'fd99::beef' } } },
|
||||
},
|
||||
{
|
||||
// A prior daemon rotated the one-use token, so StateServer deleted it.
|
||||
argsMatch: /devicectl device copy from/,
|
||||
exitCode: 1,
|
||||
stderr: 'source does not exist',
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device process launch --device TEST-UDID --terminate-existing com\.test/,
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device copy from/,
|
||||
destOutput: 'FRESH-BOOT-TOKEN\n',
|
||||
},
|
||||
]);
|
||||
const fetchCalls: Array<{ url: string; authorization?: string }> = [];
|
||||
|
||||
const r = await bootstrapTunnel({
|
||||
bundleId: 'com.test',
|
||||
spawnImpl: spawn,
|
||||
fetchImpl: (async (url, init) => {
|
||||
const u = String(url);
|
||||
const headers = init?.headers as Record<string, string> | undefined;
|
||||
fetchCalls.push({ url: u, authorization: headers?.Authorization });
|
||||
if (u.endsWith('/healthz')) {
|
||||
return new Response(JSON.stringify({ bundle_id: 'com.test' }), {
|
||||
status: 200,
|
||||
headers: { 'content-type': 'application/json' },
|
||||
});
|
||||
}
|
||||
if (u.endsWith('/auth/rotate') && headers?.Authorization === 'Bearer FRESH-BOOT-TOKEN') {
|
||||
return new Response('{"ok":true}', { status: 200 });
|
||||
}
|
||||
return new Response('unauthorized', { status: 401 });
|
||||
}) as typeof fetch,
|
||||
startupTimeoutMs: 1_000,
|
||||
});
|
||||
|
||||
expect(r.ok).toBe(true);
|
||||
expect(fetchCalls.filter((call) => call.url.endsWith('/healthz'))).toHaveLength(2);
|
||||
expect(fetchCalls.at(-1)?.authorization).toBe('Bearer FRESH-BOOT-TOKEN');
|
||||
});
|
||||
|
||||
test('rechecks bundle ownership after recovering a consumed boot token', async () => {
|
||||
const spawn = makeSpawn([
|
||||
{
|
||||
argsMatch: /devicectl list devices/,
|
||||
jsonOutput: {
|
||||
result: { devices: [{
|
||||
identifier: 'TEST-UDID',
|
||||
connectionProperties: { tunnelState: 'connected', pairingState: 'paired' },
|
||||
deviceProperties: { name: 'Test Device' },
|
||||
hardwareProperties: { productType: 'iPhone18,2' },
|
||||
}] },
|
||||
},
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device info processes/,
|
||||
jsonOutput: { result: { runningProcesses: [{ executable: 'file:\/\/\/var\/containers\/Bundle\/Application\/X\/com.test.app\/com.test' }] } },
|
||||
},
|
||||
{
|
||||
argsMatch: /devicectl device info details/,
|
||||
jsonOutput: { result: { connectionProperties: { tunnelIPAddress: 'fd99::beef' } } },
|
||||
},
|
||||
{ argsMatch: /devicectl device copy from/, exitCode: 1 },
|
||||
{
|
||||
argsMatch: /devicectl device process launch --device TEST-UDID --terminate-existing com\.test/,
|
||||
},
|
||||
{ argsMatch: /devicectl device copy from/, destOutput: 'FRESH-BOOT-TOKEN\n' },
|
||||
]);
|
||||
let healthChecks = 0;
|
||||
let rotateCalls = 0;
|
||||
|
||||
const r = await bootstrapTunnel({
|
||||
bundleId: 'com.test',
|
||||
spawnImpl: spawn,
|
||||
fetchImpl: (async (url) => {
|
||||
const u = String(url);
|
||||
if (u.endsWith('/healthz')) {
|
||||
healthChecks++;
|
||||
return new Response(JSON.stringify({
|
||||
bundle_id: healthChecks === 1 ? 'com.test' : 'com.other.debug-app',
|
||||
}), {
|
||||
status: 200,
|
||||
headers: { 'content-type': 'application/json' },
|
||||
});
|
||||
}
|
||||
rotateCalls++;
|
||||
return new Response('{"ok":true}', { status: 200 });
|
||||
}) as typeof fetch,
|
||||
startupTimeoutMs: 1_000,
|
||||
});
|
||||
|
||||
expect(r.ok).toBe(false);
|
||||
if (!r.ok) expect(r.error).toBe('wrong_app');
|
||||
expect(healthChecks).toBe(2);
|
||||
expect(rotateCalls).toBe(0);
|
||||
});
|
||||
|
||||
test('resolve_failed when hostname cant be resolved to an IPv6', async () => {
|
||||
const spawn = makeSpawn([
|
||||
{
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
// swift-tools-version:5.9
|
||||
//
|
||||
// gen-accessors-tool — SwiftPM tool that reads an app's Swift source via
|
||||
// swift-syntax, finds @Observable classes with @Snapshotable-marked fields,
|
||||
// and emits StateAccessor.swift for each one.
|
||||
// swift-syntax, finds @Observable classes with `// @Snapshotable`-marked
|
||||
// fields, and emits StateAccessor.swift for each one.
|
||||
//
|
||||
// First build is 2-5 min on a cold machine (swift-syntax compile chain).
|
||||
// Subsequent runs are content-hash-cached and finish in ~50ms.
|
||||
@@ -31,10 +31,5 @@ let package = Package(
|
||||
],
|
||||
path: "Sources/GenAccessors"
|
||||
),
|
||||
.testTarget(
|
||||
name: "GenAccessorsTests",
|
||||
dependencies: ["GenAccessors"],
|
||||
path: "Tests/GenAccessorsTests"
|
||||
),
|
||||
]
|
||||
)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
// gen-accessors entry point. Walks the input dir for *.swift files, parses
|
||||
// each via SwiftParser, finds @Observable classes with @Snapshotable-marked
|
||||
// properties, and emits StateAccessor.swift for each.
|
||||
// each via SwiftParser, finds @Observable classes with `// @Snapshotable`
|
||||
// source-marker comments (plus the legacy attribute form), and emits
|
||||
// StateAccessor.swift for each.
|
||||
//
|
||||
// Output goes to --output (default: same dir as input). Cache key is
|
||||
// computed from a composite hash and stored at
|
||||
@@ -15,6 +16,8 @@ struct AccessorSpec {
|
||||
let fields: [(name: String, typeText: String)]
|
||||
}
|
||||
|
||||
private let generatorFormatVersion = "accessor-generator-v5"
|
||||
|
||||
@main
|
||||
struct GenAccessors {
|
||||
static func main() async {
|
||||
@@ -32,38 +35,83 @@ struct GenAccessors {
|
||||
}()
|
||||
|
||||
// Walk + collect *.swift files
|
||||
guard let swiftFiles = collectSwiftFiles(at: inputDir) else {
|
||||
guard let swiftFiles = collectSwiftFiles(at: inputDir, excluding: outputDir) else {
|
||||
FileHandle.standardError.write(Data("input dir not found: \(inputDir)\n".utf8))
|
||||
exit(3)
|
||||
}
|
||||
|
||||
// Composite cache key — codex catch (source content alone misses
|
||||
// generator-logic changes).
|
||||
let cacheKey = computeCacheKey(swiftFiles: swiftFiles)
|
||||
let cacheDir = ("~/.gstack/cache/gen-accessors" as NSString).expandingTildeInPath
|
||||
// Parse + validate before consulting the cache. Invalid marked fields
|
||||
// must fail deterministically rather than being hidden by an older
|
||||
// cached output.
|
||||
var specs: [AccessorSpec] = []
|
||||
var diagnostics: [String] = []
|
||||
for path in swiftFiles {
|
||||
guard let source = try? String(contentsOfFile: path, encoding: .utf8) else { continue }
|
||||
let tree = Parser.parse(source: source)
|
||||
let visitor = ObservableClassVisitor(sourcePath: path, viewMode: .sourceAccurate)
|
||||
visitor.walk(tree)
|
||||
specs.append(contentsOf: visitor.specs)
|
||||
diagnostics.append(contentsOf: visitor.diagnostics)
|
||||
}
|
||||
var snapshotKeyOwners: [String: String] = [:]
|
||||
for spec in specs {
|
||||
for field in spec.fields {
|
||||
if let previous = snapshotKeyOwners[field.name] {
|
||||
diagnostics.append(
|
||||
"snapshot key '\(field.name)' is declared by both \(previous) and \(spec.className); "
|
||||
+ "keys must be unique across @Observable types"
|
||||
)
|
||||
} else {
|
||||
snapshotKeyOwners[field.name] = spec.className
|
||||
}
|
||||
}
|
||||
}
|
||||
if !diagnostics.isEmpty {
|
||||
let message = "gen-accessors: invalid @Snapshotable declaration(s):\n"
|
||||
+ diagnostics.map { " - \($0)" }.joined(separator: "\n") + "\n"
|
||||
FileHandle.standardError.write(Data(message.utf8))
|
||||
exit(4)
|
||||
}
|
||||
|
||||
let buildId = detectedBuildId()
|
||||
let accessorHash = computeAccessorHash(specs: specs)
|
||||
// Cache identity includes build provenance and generator ABI. The
|
||||
// separately computed accessorHash is schema-only and remains stable
|
||||
// across checkout paths, unrelated sources, and app rebuilds.
|
||||
let cacheKey = computeCacheKey(swiftFiles: swiftFiles, buildId: buildId)
|
||||
let cacheDir = getEnv("GSTACK_IOS_CACHE_ROOT")
|
||||
?? ("~/.gstack/cache/gen-accessors" as NSString).expandingTildeInPath
|
||||
let cachedOutput = "\(cacheDir)/\(cacheKey)/StateAccessor.swift"
|
||||
do {
|
||||
try FileManager.default.createDirectory(atPath: outputDir, withIntermediateDirectories: true)
|
||||
} catch {
|
||||
FileHandle.standardError.write(Data("gen-accessors: cannot create output directory: \(error)\n".utf8))
|
||||
exit(5)
|
||||
}
|
||||
if FileManager.default.fileExists(atPath: cachedOutput) {
|
||||
// Cache hit. Copy to output dir.
|
||||
try? FileManager.default.removeItem(atPath: "\(outputDir)/StateAccessor.swift")
|
||||
try? FileManager.default.copyItem(atPath: cachedOutput, toPath: "\(outputDir)/StateAccessor.swift")
|
||||
let finalOutput = "\(outputDir)/StateAccessor.swift"
|
||||
do {
|
||||
if FileManager.default.fileExists(atPath: finalOutput) {
|
||||
try FileManager.default.removeItem(atPath: finalOutput)
|
||||
}
|
||||
try FileManager.default.copyItem(atPath: cachedOutput, toPath: finalOutput)
|
||||
} catch {
|
||||
FileHandle.standardError.write(Data("gen-accessors: cannot restore cached output: \(error)\n".utf8))
|
||||
exit(5)
|
||||
}
|
||||
print("gen-accessors: cache hit (\(cacheKey))")
|
||||
return
|
||||
}
|
||||
|
||||
// Parse + extract specs
|
||||
var specs: [AccessorSpec] = []
|
||||
for path in swiftFiles {
|
||||
guard let source = try? String(contentsOfFile: path, encoding: .utf8) else { continue }
|
||||
let tree = Parser.parse(source: source)
|
||||
let visitor = ObservableClassVisitor(viewMode: .sourceAccurate)
|
||||
visitor.walk(tree)
|
||||
specs.append(contentsOf: visitor.specs)
|
||||
}
|
||||
|
||||
// Emit
|
||||
let output = render(specs: specs, buildId: getEnv("APP_BUILD_ID") ?? "unknown", accessorHash: cacheKey)
|
||||
try? FileManager.default.createDirectory(atPath: outputDir, withIntermediateDirectories: true)
|
||||
try? output.write(toFile: "\(outputDir)/StateAccessor.swift", atomically: true, encoding: .utf8)
|
||||
let output = render(specs: specs, buildId: buildId, accessorHash: accessorHash)
|
||||
do {
|
||||
try output.write(toFile: "\(outputDir)/StateAccessor.swift", atomically: true, encoding: .utf8)
|
||||
} catch {
|
||||
FileHandle.standardError.write(Data("gen-accessors: cannot write output: \(error)\n".utf8))
|
||||
exit(5)
|
||||
}
|
||||
|
||||
// Populate cache
|
||||
try? FileManager.default.createDirectory(atPath: "\(cacheDir)/\(cacheKey)", withIntermediateDirectories: true)
|
||||
@@ -72,46 +120,154 @@ struct GenAccessors {
|
||||
print("gen-accessors: wrote \(specs.count) accessor(s) to \(outputDir)/StateAccessor.swift")
|
||||
}
|
||||
|
||||
static func collectSwiftFiles(at path: String) -> [String]? {
|
||||
guard let enumerator = FileManager.default.enumerator(atPath: path) else { return nil }
|
||||
static func collectSwiftFiles(at path: String, excluding outputPath: String) -> [String]? {
|
||||
let inputURL = URL(fileURLWithPath: path).standardizedFileURL
|
||||
let outputURL = URL(fileURLWithPath: outputPath).standardizedFileURL
|
||||
var isDirectory: ObjCBool = false
|
||||
guard FileManager.default.fileExists(atPath: inputURL.path, isDirectory: &isDirectory),
|
||||
isDirectory.boolValue,
|
||||
let enumerator = FileManager.default.enumerator(
|
||||
at: inputURL,
|
||||
includingPropertiesForKeys: [.isDirectoryKey],
|
||||
options: []
|
||||
) else { return nil }
|
||||
|
||||
// When --output is the input root, scan the root but still exclude
|
||||
// StateAccessor.swift. For a nested output, skip the entire subtree.
|
||||
let shouldExcludeOutputSubtree = outputURL.path != inputURL.path
|
||||
var files: [String] = []
|
||||
for case let f as String in enumerator {
|
||||
if f.hasSuffix(".swift") { files.append("\(path)/\(f)") }
|
||||
for case let fileURL as URL in enumerator {
|
||||
let normalized = fileURL.standardizedFileURL
|
||||
let values = try? normalized.resourceValues(forKeys: [.isDirectoryKey])
|
||||
if values?.isDirectory == true {
|
||||
if normalized.lastPathComponent == "DebugBridgeGenerated"
|
||||
|| (shouldExcludeOutputSubtree && normalized.path == outputURL.path) {
|
||||
enumerator.skipDescendants()
|
||||
}
|
||||
continue
|
||||
}
|
||||
guard normalized.pathExtension == "swift",
|
||||
normalized.lastPathComponent != "StateAccessor.swift" else { continue }
|
||||
files.append(normalized.path)
|
||||
}
|
||||
return files.sorted()
|
||||
}
|
||||
|
||||
static func computeCacheKey(swiftFiles: [String]) -> String {
|
||||
static func computeCacheKey(swiftFiles: [String], buildId: String) -> String {
|
||||
// Codex-flagged: hash must include Swift version, tool git rev, platform.
|
||||
let swiftVer = getEnv("SWIFT_VERSION") ?? "unknown"
|
||||
let toolRev = getEnv("GEN_ACCESSORS_REV") ?? "dev"
|
||||
let platform = "darwin-arm64" // simplified for the test harness
|
||||
var combined = "swift=\(swiftVer)|tool=\(toolRev)|platform=\(platform)|"
|
||||
let toolRev = getEnv("GEN_ACCESSORS_REV") ?? generatorFormatVersion
|
||||
#if arch(arm64)
|
||||
let platform = "darwin-arm64"
|
||||
#elseif arch(x86_64)
|
||||
let platform = "darwin-x86_64"
|
||||
#else
|
||||
let platform = "darwin-unknown"
|
||||
#endif
|
||||
var combined = Data("\(generatorFormatVersion)|swift=\(swiftVer)|tool=\(toolRev)|platform=\(platform)|build=\(buildId)|".utf8)
|
||||
for path in swiftFiles {
|
||||
if let data = try? Data(contentsOf: URL(fileURLWithPath: path)) {
|
||||
combined += "\(path):\(data.count):\(data.sha256())|"
|
||||
// Do not include absolute checkout paths in cache identity.
|
||||
combined.append(Data("\(data.count):".utf8))
|
||||
combined.append(data)
|
||||
combined.append(Data("|".utf8))
|
||||
}
|
||||
}
|
||||
return combined.data(using: .utf8)!.sha256()
|
||||
return combined.sha256()
|
||||
}
|
||||
|
||||
static func computeAccessorHash(specs: [AccessorSpec]) -> String {
|
||||
var signature = "snapshot-schema-v1\n"
|
||||
for spec in specs {
|
||||
signature += "C\(spec.className.utf8.count):\(spec.className)\n"
|
||||
for field in spec.fields {
|
||||
signature += "F\(field.name.utf8.count):\(field.name)"
|
||||
signature += "T\(field.typeText.utf8.count):\(field.typeText)\n"
|
||||
}
|
||||
signature += "E\n"
|
||||
}
|
||||
return signature.sha256()
|
||||
}
|
||||
|
||||
static func render(specs: [AccessorSpec], buildId: String, accessorHash: String) -> String {
|
||||
var out = "// AUTO-GENERATED — DO NOT EDIT. Regenerate with /ios-sync.\n"
|
||||
out += "#if DEBUG\nimport Foundation\nimport DebugBridge\n\n"
|
||||
out += "#if DEBUG\nimport Foundation\nimport DebugBridgeCore\n\n"
|
||||
if !specs.isEmpty {
|
||||
// JSONSerialization produces Foundation bridge objects. Direct
|
||||
// `as?` casts let NSNumber cross-cast between Bool and numeric
|
||||
// Swift types. Round-tripping through JSONDecoder enforces the
|
||||
// declared Codable shape (including every collection element)
|
||||
// and preserves a successful Optional nil as a double Optional.
|
||||
out += "private enum _GStackDebugBridgeSnapshotJSON {\n"
|
||||
out += " private struct Box<Value: Decodable>: Decodable {\n"
|
||||
out += " let value: Value\n"
|
||||
out += " }\n\n"
|
||||
out += " static func decode<Value: Decodable>(_ value: Any, as _: Value.Type) -> Value? {\n"
|
||||
out += " let object: [String: Any] = [\"value\": value]\n"
|
||||
out += " guard JSONSerialization.isValidJSONObject(object),\n"
|
||||
out += " let data = try? JSONSerialization.data(withJSONObject: object) else {\n"
|
||||
out += " return nil\n"
|
||||
out += " }\n"
|
||||
out += " do {\n"
|
||||
out += " return try JSONDecoder().decode(Box<Value>.self, from: data).value\n"
|
||||
out += " } catch {\n"
|
||||
out += " return nil\n"
|
||||
out += " }\n"
|
||||
out += " }\n"
|
||||
out += "}\n\n"
|
||||
}
|
||||
for spec in specs {
|
||||
out += "@MainActor\npublic enum \(spec.className)Accessor {\n"
|
||||
out += " public static func register(_ state: \(spec.className)) {\n"
|
||||
// Accessors live in the app target beside its usually-internal
|
||||
// state types. A public signature cannot expose an internal type.
|
||||
out += "@MainActor\nenum \(spec.className)Accessor {\n"
|
||||
out += " static func register(_ state: \(spec.className)) {\n"
|
||||
out += " StateServer.shared.register(\n"
|
||||
out += " buildId: \"\(buildId)\",\n"
|
||||
out += " accessorHash: \"\(accessorHash)\",\n"
|
||||
out += " atomicRestore: { _ in .ok }\n"
|
||||
out += " buildId: {\n"
|
||||
out += " let shortVersion = Bundle.main.object(forInfoDictionaryKey: \"CFBundleShortVersionString\") as? String\n"
|
||||
out += " let bundleVersion = Bundle.main.object(forInfoDictionaryKey: \"CFBundleVersion\") as? String\n"
|
||||
out += " if let shortVersion, let bundleVersion { return \"\\(shortVersion) (\\(bundleVersion))\" }\n"
|
||||
out += " return shortVersion ?? bundleVersion ?? \(String(reflecting: buildId))\n"
|
||||
out += " }(),\n"
|
||||
out += " accessorHash: \(String(reflecting: accessorHash)),\n"
|
||||
out += " atomicRestore: { keys, apply in\n"
|
||||
out += " // Validate every key and value before assignment.\n"
|
||||
out += " // StateServer invokes every model once with apply=false,\n"
|
||||
out += " // then applies every validated model with apply=true.\n"
|
||||
for (index, field) in spec.fields.enumerated() {
|
||||
let (name, typeText) = field
|
||||
out += " guard let raw\(index) = keys[\"\(name)\"] else {\n"
|
||||
out += " return .missingKey(\"\(name)\")\n"
|
||||
out += " }\n"
|
||||
out += " guard let restored\(index): \(typeText) = _GStackDebugBridgeSnapshotJSON.decode(raw\(index), as: \(typeText).self) else {\n"
|
||||
out += " return .typeMismatch(\"\(name)\")\n"
|
||||
out += " }\n"
|
||||
}
|
||||
out += " if apply {\n"
|
||||
for (index, field) in spec.fields.enumerated() {
|
||||
out += " state.\(field.name) = restored\(index)\n"
|
||||
}
|
||||
out += " }\n"
|
||||
out += " return .ok\n"
|
||||
out += " }\n"
|
||||
out += " )\n"
|
||||
for (name, _) in spec.fields {
|
||||
for (name, typeText) in spec.fields {
|
||||
let wrapped = optionalWrappedType(typeText)
|
||||
out += " StateServer.shared.registerAccessor(\n"
|
||||
out += " key: \"\(name)\",\n"
|
||||
out += " type: \"Any\",\n"
|
||||
out += " read: { state.\(name) as Any? },\n"
|
||||
out += " write: { _ in false }\n"
|
||||
out += " type: \"\(typeText)\",\n"
|
||||
if wrapped != nil {
|
||||
out += " read: {\n"
|
||||
out += " guard let value = state.\(name) else { return NSNull() }\n"
|
||||
out += " return value as Any\n"
|
||||
out += " },\n"
|
||||
} else {
|
||||
out += " read: { state.\(name) as Any? },\n"
|
||||
}
|
||||
out += " write: { value in\n"
|
||||
out += " guard let typed: \(typeText) = _GStackDebugBridgeSnapshotJSON.decode(value, as: \(typeText).self) else { return false }\n"
|
||||
out += " state.\(name) = typed\n"
|
||||
out += " return true\n"
|
||||
out += " }\n"
|
||||
out += " )\n"
|
||||
}
|
||||
out += " }\n}\n\n"
|
||||
@@ -123,6 +279,59 @@ struct GenAccessors {
|
||||
|
||||
final class ObservableClassVisitor: SyntaxVisitor {
|
||||
var specs: [AccessorSpec] = []
|
||||
var diagnostics: [String] = []
|
||||
private let sourcePath: String
|
||||
|
||||
init(sourcePath: String, viewMode: SyntaxTreeViewMode) {
|
||||
self.sourcePath = sourcePath
|
||||
super.init(viewMode: viewMode)
|
||||
}
|
||||
|
||||
private func hasSnapshotableMarker(_ declaration: VariableDeclSyntax) -> Bool {
|
||||
// Preserve compatibility with source that defines a custom attribute
|
||||
// or wrapper, even though that form conflicts with @Observable in
|
||||
// ordinary app models.
|
||||
if declaration.attributes.contains(where: { attribute in
|
||||
guard let attribute = attribute.as(AttributeSyntax.self) else { return false }
|
||||
return attribute.attributeName.trimmedDescription == "Snapshotable"
|
||||
}) {
|
||||
return true
|
||||
}
|
||||
|
||||
// Match a standalone ordinary line-comment trivia piece exactly.
|
||||
// Avoid declaration.description/contains: both would accept prose
|
||||
// such as `// do not expose through @Snapshotable`.
|
||||
return declaration.leadingTrivia.contains { piece in
|
||||
guard case .lineComment(let text) = piece else { return false }
|
||||
return text.dropFirst(2).trimmingCharacters(in: .whitespaces) == "@Snapshotable"
|
||||
}
|
||||
}
|
||||
|
||||
private func enclosingScopeDescription(for node: ClassDeclSyntax) -> String? {
|
||||
var ancestor = Syntax(node).parent
|
||||
while let current = ancestor {
|
||||
if let declaration = current.as(ClassDeclSyntax.self) {
|
||||
return "class \(declaration.name.text)"
|
||||
}
|
||||
if let declaration = current.as(StructDeclSyntax.self) {
|
||||
return "struct \(declaration.name.text)"
|
||||
}
|
||||
if let declaration = current.as(EnumDeclSyntax.self) {
|
||||
return "enum \(declaration.name.text)"
|
||||
}
|
||||
if let declaration = current.as(ActorDeclSyntax.self) {
|
||||
return "actor \(declaration.name.text)"
|
||||
}
|
||||
if let declaration = current.as(ExtensionDeclSyntax.self) {
|
||||
return "extension \(declaration.extendedType.trimmedDescription)"
|
||||
}
|
||||
if current.is(CodeBlockSyntax.self) {
|
||||
return "a local scope"
|
||||
}
|
||||
ancestor = current.parent
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
override func visit(_ node: ClassDeclSyntax) -> SyntaxVisitorContinueKind {
|
||||
// Look for @Observable attribute
|
||||
@@ -133,23 +342,88 @@ final class ObservableClassVisitor: SyntaxVisitor {
|
||||
guard isObservable else { return .visitChildren }
|
||||
|
||||
let className = node.name.text
|
||||
let markedMembers = node.memberBlock.members.compactMap {
|
||||
$0.decl.as(VariableDeclSyntax.self)
|
||||
}.filter(hasSnapshotableMarker)
|
||||
if !markedMembers.isEmpty, let enclosingScope = enclosingScopeDescription(for: node) {
|
||||
diagnostics.append(
|
||||
"\((sourcePath as NSString).lastPathComponent): nested @Observable class "
|
||||
+ "\(className) inside \(enclosingScope) is unsupported; "
|
||||
+ "move snapshot-enabled models to file scope"
|
||||
)
|
||||
// Continue walking so a more deeply nested marked model is also
|
||||
// diagnosed rather than silently omitted.
|
||||
return .visitChildren
|
||||
}
|
||||
var fields: [(String, String)] = []
|
||||
|
||||
for member in node.memberBlock.members {
|
||||
guard let varDecl = member.decl.as(VariableDeclSyntax.self) else { continue }
|
||||
// Field must be marked @Snapshotable to be included
|
||||
let isSnapshotable = varDecl.attributes.contains(where: { attr in
|
||||
guard let attr = attr.as(AttributeSyntax.self) else { return false }
|
||||
return attr.attributeName.trimmedDescription == "Snapshotable"
|
||||
})
|
||||
guard isSnapshotable else { continue }
|
||||
// Field must opt in with the source marker (or legacy attribute).
|
||||
guard hasSnapshotableMarker(varDecl) else { continue }
|
||||
|
||||
let bindingName = varDecl.bindings.first?
|
||||
.pattern.as(IdentifierPatternSyntax.self)?.identifier.text ?? "<unknown>"
|
||||
let context = "\((sourcePath as NSString).lastPathComponent): \(className).\(bindingName)"
|
||||
if varDecl.bindingSpecifier.text == "let" {
|
||||
diagnostics.append("\(context) must be declared var, not let")
|
||||
continue
|
||||
}
|
||||
let modifierNames = varDecl.modifiers.map { modifier -> String in
|
||||
let detail = modifier.detail?.trimmedDescription ?? ""
|
||||
return modifier.name.text + detail
|
||||
}
|
||||
if modifierNames.contains(where: {
|
||||
$0 == "private" || $0 == "fileprivate"
|
||||
|| $0 == "private(set)" || $0 == "fileprivate(set)"
|
||||
}) {
|
||||
diagnostics.append("\(context) cannot be private, fileprivate, private(set), or fileprivate(set)")
|
||||
continue
|
||||
}
|
||||
if modifierNames.contains("static") || modifierNames.contains("class") {
|
||||
diagnostics.append("\(context) must be an instance property")
|
||||
continue
|
||||
}
|
||||
if varDecl.bindings.count != 1 {
|
||||
diagnostics.append("\(context) declaration must contain exactly one binding")
|
||||
continue
|
||||
}
|
||||
|
||||
for binding in varDecl.bindings {
|
||||
if let pattern = binding.pattern.as(IdentifierPatternSyntax.self) {
|
||||
let name = pattern.identifier.text
|
||||
let typeText = binding.typeAnnotation?.type.trimmedDescription ?? "Any"
|
||||
fields.append((name, typeText))
|
||||
guard let pattern = binding.pattern.as(IdentifierPatternSyntax.self) else {
|
||||
diagnostics.append("\(context) only supports an identifier binding")
|
||||
continue
|
||||
}
|
||||
// An initializer plus an accessor block is a stored property
|
||||
// with observers. Without an initializer, conservatively
|
||||
// reject the block rather than emitting a setter for a
|
||||
// computed/read-only declaration.
|
||||
if binding.accessorBlock != nil && binding.initializer == nil {
|
||||
diagnostics.append("\(context) must be stored and writable")
|
||||
continue
|
||||
}
|
||||
guard let annotation = binding.typeAnnotation else {
|
||||
diagnostics.append("\(context) requires an explicit type annotation")
|
||||
continue
|
||||
}
|
||||
let name = pattern.identifier.text
|
||||
let typeText = annotation.type.trimmedDescription
|
||||
.split(whereSeparator: { $0.isWhitespace })
|
||||
.joined(separator: " ")
|
||||
switch parseJSONSnapshotType(typeText) {
|
||||
case .valid:
|
||||
break
|
||||
case .implicitlyUnwrappedOptional:
|
||||
diagnostics.append("\(context) cannot use an implicitly unwrapped Optional type")
|
||||
continue
|
||||
case .nestedOptional:
|
||||
diagnostics.append("\(context) cannot use a nested Optional type")
|
||||
continue
|
||||
case .unsupported:
|
||||
diagnostics.append("\(context) uses unsupported non-JSON snapshot type '\(typeText)'")
|
||||
continue
|
||||
}
|
||||
fields.append((name, typeText))
|
||||
}
|
||||
}
|
||||
|
||||
@@ -160,10 +434,233 @@ final class ObservableClassVisitor: SyntaxVisitor {
|
||||
}
|
||||
}
|
||||
|
||||
private indirect enum JSONSnapshotType {
|
||||
case scalar
|
||||
case optional(JSONSnapshotType)
|
||||
case array(JSONSnapshotType)
|
||||
case dictionary(JSONSnapshotType)
|
||||
|
||||
var isOptional: Bool {
|
||||
if case .optional = self { return true }
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
private enum JSONSnapshotTypeParseResult {
|
||||
case valid(JSONSnapshotType)
|
||||
case implicitlyUnwrappedOptional
|
||||
case nestedOptional
|
||||
case unsupported
|
||||
}
|
||||
|
||||
/// Parse the deliberately small set of Swift types that can make a lossless
|
||||
/// trip through JSONSerialization and JSONDecoder without application-defined
|
||||
/// encoding behavior. Type aliases and arbitrary Codable models are rejected:
|
||||
/// the bridge has no compiler/type-checker context in which to prove that they
|
||||
/// are JSON-native.
|
||||
private func parseJSONSnapshotType(_ source: String) -> JSONSnapshotTypeParseResult {
|
||||
let type = source.trimmingCharacters(in: .whitespacesAndNewlines)
|
||||
guard !type.isEmpty else { return .unsupported }
|
||||
|
||||
if type.hasSuffix("!") {
|
||||
return .implicitlyUnwrappedOptional
|
||||
}
|
||||
|
||||
if type.hasSuffix("?") {
|
||||
let wrappedText = String(type.dropLast()).trimmingCharacters(in: .whitespacesAndNewlines)
|
||||
switch parseJSONSnapshotType(wrappedText) {
|
||||
case .valid(let wrapped):
|
||||
return wrapped.isOptional ? .nestedOptional : .valid(.optional(wrapped))
|
||||
case let issue:
|
||||
return issue
|
||||
}
|
||||
}
|
||||
|
||||
if let bracketContents = outerDelimitedContents(type, open: "[", close: "]") {
|
||||
let dictionaryParts = splitTopLevel(bracketContents, separator: ":")
|
||||
if dictionaryParts.count == 1 {
|
||||
switch parseJSONSnapshotType(dictionaryParts[0]) {
|
||||
case .valid(let element): return .valid(.array(element))
|
||||
case let issue: return issue
|
||||
}
|
||||
}
|
||||
guard dictionaryParts.count == 2, isStringType(dictionaryParts[0]) else {
|
||||
return .unsupported
|
||||
}
|
||||
switch parseJSONSnapshotType(dictionaryParts[1]) {
|
||||
case .valid(let value): return .valid(.dictionary(value))
|
||||
case let issue: return issue
|
||||
}
|
||||
}
|
||||
|
||||
if let generic = genericTypeParts(type) {
|
||||
let base = compactTypeName(generic.base)
|
||||
if base == "Optional" || base == "Swift.Optional" {
|
||||
guard generic.arguments.count == 1 else { return .unsupported }
|
||||
switch parseJSONSnapshotType(generic.arguments[0]) {
|
||||
case .valid(let wrapped):
|
||||
return wrapped.isOptional ? .nestedOptional : .valid(.optional(wrapped))
|
||||
case let issue:
|
||||
return issue
|
||||
}
|
||||
}
|
||||
if base == "Array" || base == "Swift.Array" {
|
||||
guard generic.arguments.count == 1 else { return .unsupported }
|
||||
switch parseJSONSnapshotType(generic.arguments[0]) {
|
||||
case .valid(let element): return .valid(.array(element))
|
||||
case let issue: return issue
|
||||
}
|
||||
}
|
||||
if base == "Dictionary" || base == "Swift.Dictionary" {
|
||||
guard generic.arguments.count == 2, isStringType(generic.arguments[0]) else {
|
||||
return .unsupported
|
||||
}
|
||||
switch parseJSONSnapshotType(generic.arguments[1]) {
|
||||
case .valid(let value): return .valid(.dictionary(value))
|
||||
case let issue: return issue
|
||||
}
|
||||
}
|
||||
return .unsupported
|
||||
}
|
||||
|
||||
let scalar = compactTypeName(type)
|
||||
let supportedScalars: Set<String> = [
|
||||
"String", "Swift.String",
|
||||
"Bool", "Swift.Bool",
|
||||
"Int", "Swift.Int", "Int8", "Swift.Int8", "Int16", "Swift.Int16",
|
||||
"Int32", "Swift.Int32", "Int64", "Swift.Int64",
|
||||
"UInt", "Swift.UInt", "UInt8", "Swift.UInt8", "UInt16", "Swift.UInt16",
|
||||
"UInt32", "Swift.UInt32", "UInt64", "Swift.UInt64",
|
||||
"Float", "Swift.Float", "Double", "Swift.Double",
|
||||
"CGFloat", "CoreGraphics.CGFloat",
|
||||
]
|
||||
return supportedScalars.contains(scalar) ? .valid(.scalar) : .unsupported
|
||||
}
|
||||
|
||||
private func isStringType(_ source: String) -> Bool {
|
||||
let type = compactTypeName(source)
|
||||
return type == "String" || type == "Swift.String"
|
||||
}
|
||||
|
||||
private func compactTypeName(_ source: String) -> String {
|
||||
source.filter { !$0.isWhitespace }
|
||||
}
|
||||
|
||||
private func outerDelimitedContents(_ source: String, open: Character, close: Character) -> String? {
|
||||
let characters = Array(source)
|
||||
guard characters.first == open, characters.last == close else { return nil }
|
||||
var depth = 0
|
||||
for (index, character) in characters.enumerated() {
|
||||
if character == open {
|
||||
depth += 1
|
||||
} else if character == close {
|
||||
depth -= 1
|
||||
guard depth >= 0 else { return nil }
|
||||
if depth == 0, index != characters.count - 1 { return nil }
|
||||
}
|
||||
}
|
||||
guard depth == 0 else { return nil }
|
||||
return String(characters.dropFirst().dropLast())
|
||||
}
|
||||
|
||||
private func genericTypeParts(_ source: String) -> (base: String, arguments: [String])? {
|
||||
let characters = Array(source)
|
||||
guard let openIndex = characters.firstIndex(of: "<") else { return nil }
|
||||
var depth = 0
|
||||
var closeIndex: Int?
|
||||
for index in openIndex..<characters.count {
|
||||
if characters[index] == "<" {
|
||||
depth += 1
|
||||
} else if characters[index] == ">" {
|
||||
depth -= 1
|
||||
guard depth >= 0 else { return nil }
|
||||
if depth == 0 {
|
||||
closeIndex = index
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
guard let closeIndex, closeIndex == characters.count - 1 else { return nil }
|
||||
let base = String(characters[..<openIndex]).trimmingCharacters(in: .whitespacesAndNewlines)
|
||||
let argumentsText = String(characters[(openIndex + 1)..<closeIndex])
|
||||
let arguments = splitTopLevel(argumentsText, separator: ",")
|
||||
guard !base.isEmpty, !arguments.isEmpty else { return nil }
|
||||
return (base, arguments)
|
||||
}
|
||||
|
||||
private func splitTopLevel(_ source: String, separator: Character) -> [String] {
|
||||
let characters = Array(source)
|
||||
var angleDepth = 0
|
||||
var squareDepth = 0
|
||||
var parenDepth = 0
|
||||
var start = 0
|
||||
var parts: [String] = []
|
||||
|
||||
for (index, character) in characters.enumerated() {
|
||||
switch character {
|
||||
case "<": angleDepth += 1
|
||||
case ">": angleDepth -= 1
|
||||
case "[": squareDepth += 1
|
||||
case "]": squareDepth -= 1
|
||||
case "(": parenDepth += 1
|
||||
case ")": parenDepth -= 1
|
||||
default: break
|
||||
}
|
||||
if character == separator, angleDepth == 0, squareDepth == 0, parenDepth == 0 {
|
||||
parts.append(
|
||||
String(characters[start..<index]).trimmingCharacters(in: .whitespacesAndNewlines)
|
||||
)
|
||||
start = index + 1
|
||||
}
|
||||
}
|
||||
parts.append(String(characters[start...]).trimmingCharacters(in: .whitespacesAndNewlines))
|
||||
return parts
|
||||
}
|
||||
|
||||
func getEnv(_ key: String) -> String? {
|
||||
ProcessInfo.processInfo.environment[key]
|
||||
}
|
||||
|
||||
func detectedBuildId() -> String {
|
||||
if let explicit = getEnv("APP_BUILD_ID"), !explicit.isEmpty { return explicit }
|
||||
let marketing = getEnv("MARKETING_VERSION")
|
||||
let build = getEnv("CURRENT_PROJECT_VERSION")
|
||||
if let marketing, let build, !marketing.isEmpty, !build.isEmpty {
|
||||
return "\(marketing) (\(build))"
|
||||
}
|
||||
if let build, !build.isEmpty { return build }
|
||||
return "unknown"
|
||||
}
|
||||
|
||||
func optionalWrappedType(_ typeText: String) -> String? {
|
||||
let type = typeText.trimmingCharacters(in: .whitespacesAndNewlines)
|
||||
if type.hasSuffix("?") {
|
||||
let wrapped = String(type.dropLast()).trimmingCharacters(in: .whitespacesAndNewlines)
|
||||
return wrapped.isEmpty ? nil : wrapped
|
||||
}
|
||||
|
||||
guard let optionalRange = type.range(of: #"^Optional\s*<"#, options: .regularExpression),
|
||||
let open = type[optionalRange].lastIndex(of: "<") else { return nil }
|
||||
let openIndex = type.distance(from: type.startIndex, to: open)
|
||||
var depth = 0
|
||||
for (offset, char) in type.enumerated() where offset >= openIndex {
|
||||
if char == "<" { depth += 1 }
|
||||
else if char == ">" {
|
||||
depth -= 1
|
||||
if depth == 0 {
|
||||
let close = type.index(type.startIndex, offsetBy: offset)
|
||||
guard type[type.index(after: close)...].trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
|
||||
return nil
|
||||
}
|
||||
let wrappedStart = type.index(after: open)
|
||||
let wrapped = String(type[wrappedStart..<close]).trimmingCharacters(in: .whitespacesAndNewlines)
|
||||
return wrapped.isEmpty ? nil : wrapped
|
||||
}
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
import CryptoKit
|
||||
|
||||
extension Data {
|
||||
|
||||
@@ -1,11 +1,14 @@
|
||||
// Tests for the gen-accessors TS port. Covers:
|
||||
//
|
||||
// - Parse: 3 regex-failure-mode fixtures from the fork (codex catch)
|
||||
// - Parse: lexical marker isolation + invalid declaration diagnostics
|
||||
// - Cache: same input → same key; different swift version → different key;
|
||||
// different tool rev → different key; file modified → different key
|
||||
// different tool rev/build provenance → different key
|
||||
// - Schema: stable hash depends only on ordered accessor signatures
|
||||
// - Optional: NSNull read/write/restore behavior and Swift type checking
|
||||
// - Prune: >30d entries removed, recent kept
|
||||
|
||||
import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
|
||||
import { spawnSync } from 'child_process';
|
||||
import { mkdtempSync, rmSync, writeFileSync, existsSync, readFileSync, mkdirSync, utimesSync } from 'fs';
|
||||
import { join } from 'path';
|
||||
import { tmpdir } from 'os';
|
||||
@@ -13,9 +16,11 @@ import {
|
||||
collectSwiftFiles,
|
||||
parseSwift,
|
||||
computeCacheKey,
|
||||
computeAccessorHash,
|
||||
generate,
|
||||
pruneCache,
|
||||
render,
|
||||
AccessorGenerationError,
|
||||
type AccessorSpec,
|
||||
} from './gen-accessors';
|
||||
|
||||
@@ -30,12 +35,14 @@ afterEach(() => {
|
||||
});
|
||||
|
||||
describe('parseSwift — fork regex-failure-mode fixtures', () => {
|
||||
test('parses @Observable class with simple @Snapshotable fields', () => {
|
||||
test('parses @Observable class with source-marker comments', () => {
|
||||
const src = `
|
||||
@Observable
|
||||
final class AppState {
|
||||
@Snapshotable var isLoggedIn: Bool = false
|
||||
@Snapshotable var username: String = ""
|
||||
// @Snapshotable
|
||||
var isLoggedIn: Bool = false
|
||||
// @Snapshotable
|
||||
var username: String = ""
|
||||
var notSnapshotable: Int = 0
|
||||
}
|
||||
`;
|
||||
@@ -46,12 +53,100 @@ final class AppState {
|
||||
expect(specs[0]!.fields.find(f => f.name === 'isLoggedIn')!.typeText).toBe('Bool');
|
||||
});
|
||||
|
||||
test('retains legacy @Snapshotable attribute parsing', () => {
|
||||
const specs = parseSwift(`
|
||||
@Observable
|
||||
final class LegacyState {
|
||||
@Snapshotable var counter: Int = 0
|
||||
}
|
||||
`);
|
||||
expect(specs).toEqual([{
|
||||
className: 'LegacyState',
|
||||
fields: [{ name: 'counter', typeText: 'Int' }],
|
||||
}]);
|
||||
});
|
||||
|
||||
test('does not treat documentation prose as a source marker', () => {
|
||||
const specs = parseSwift(`
|
||||
@Observable
|
||||
final class PrivateState {
|
||||
/// Do not expose this field through @Snapshotable.
|
||||
var token: String = "secret"
|
||||
}
|
||||
`);
|
||||
expect(specs).toHaveLength(0);
|
||||
});
|
||||
|
||||
test('does not let a trailing marker comment bleed into the next field', () => {
|
||||
const specs = parseSwift(`
|
||||
@Observable
|
||||
final class PrivateState {
|
||||
var oldValue: Int = 0 // @Snapshotable
|
||||
var nextValue: Int = 1
|
||||
}
|
||||
`);
|
||||
expect(specs).toHaveLength(0);
|
||||
});
|
||||
|
||||
test('ignores exact-looking markers inside nested block comments', () => {
|
||||
const specs = parseSwift(`
|
||||
@Observable
|
||||
final class PrivateState {
|
||||
/*
|
||||
/* // @Snapshotable */
|
||||
// @Snapshotable
|
||||
var leaked: String = "secret"
|
||||
*/
|
||||
// @Snapshotable
|
||||
var visible: Int = 1
|
||||
}
|
||||
`);
|
||||
expect(specs).toEqual([{
|
||||
className: 'PrivateState',
|
||||
fields: [{ name: 'visible', typeText: 'Int' }],
|
||||
}]);
|
||||
});
|
||||
|
||||
test('ignores declarations and markers inside multiline and raw strings', () => {
|
||||
const specs = parseSwift(`
|
||||
let ordinary = """
|
||||
@Observable class FakeA {
|
||||
// @Snapshotable
|
||||
var leaked: Int = 0
|
||||
}
|
||||
"""
|
||||
let raw = #"""
|
||||
@Observable class FakeB { @Snapshotable var leaked: String = "" }
|
||||
"""#
|
||||
@Observable
|
||||
final class RealState {
|
||||
// @Snapshotable
|
||||
var safe: Bool = true
|
||||
}
|
||||
`);
|
||||
expect(specs).toEqual([{
|
||||
className: 'RealState',
|
||||
fields: [{ name: 'safe', typeText: 'Bool' }],
|
||||
}]);
|
||||
});
|
||||
|
||||
test('ignores marker words in standalone trailing prose', () => {
|
||||
const specs = parseSwift(`
|
||||
@Observable
|
||||
final class PrivateState {
|
||||
// @Snapshotable fields are intentionally disabled here.
|
||||
var token: String = "secret"
|
||||
}
|
||||
`);
|
||||
expect(specs).toHaveLength(0);
|
||||
});
|
||||
|
||||
test('handles @Snapshotable on multi-line type signatures', () => {
|
||||
const src = `
|
||||
@Observable
|
||||
class Cart {
|
||||
@Snapshotable var items:
|
||||
[CartItem<Detail>]
|
||||
[Dictionary<String, [Int]>]
|
||||
= []
|
||||
var unrelated: Int = 0
|
||||
}
|
||||
@@ -60,20 +155,67 @@ class Cart {
|
||||
expect(specs).toHaveLength(1);
|
||||
expect(specs[0]!.fields).toHaveLength(1);
|
||||
expect(specs[0]!.fields[0]!.name).toBe('items');
|
||||
expect(specs[0]!.fields[0]!.typeText).toContain('CartItem');
|
||||
expect(specs[0]!.fields[0]!.typeText).toContain('Dictionary');
|
||||
});
|
||||
|
||||
test('handles generic types in property signatures', () => {
|
||||
test('handles JSON-compatible generic types in property signatures', () => {
|
||||
const src = `
|
||||
@Observable
|
||||
class Repo {
|
||||
@Snapshotable var pages: Dictionary<String, [Result<Item, Error>]> = [:]
|
||||
@Snapshotable var pages: Dictionary<String, [Optional<Int>]> = [:]
|
||||
}
|
||||
`;
|
||||
const specs = parseSwift(src);
|
||||
expect(specs).toHaveLength(1);
|
||||
expect(specs[0]!.fields[0]!.typeText).toContain('Dictionary');
|
||||
expect(specs[0]!.fields[0]!.typeText).toContain('Result');
|
||||
expect(specs[0]!.fields[0]!.typeText).toContain('Optional');
|
||||
});
|
||||
|
||||
test('accepts qualified JSON-native scalar and collection spellings', () => {
|
||||
const specs = parseSwift(`
|
||||
@Observable
|
||||
class Metrics {
|
||||
// @Snapshotable
|
||||
var ratio: CoreGraphics.CGFloat = 0
|
||||
// @Snapshotable
|
||||
var counts: Swift.Array<Swift.Int> = []
|
||||
}
|
||||
`);
|
||||
expect(specs[0]!.fields.map((field) => field.typeText)).toEqual([
|
||||
'CoreGraphics.CGFloat',
|
||||
'Swift.Array<Swift.Int>',
|
||||
]);
|
||||
});
|
||||
|
||||
test('rejects custom values that Foundation JSON cannot serialize', () => {
|
||||
expect(() => parseSwift(`
|
||||
@Observable
|
||||
class Repo {
|
||||
// @Snapshotable
|
||||
var pages: Dictionary<String, [Result<Item, Error>]> = [:]
|
||||
}
|
||||
`)).toThrow("unsupported snapshot type 'Result<Item,Error>'");
|
||||
});
|
||||
|
||||
test('rejects nested observable types instead of emitting an unqualified reference', () => {
|
||||
expect(() => parseSwift(`
|
||||
enum Namespace {
|
||||
@Observable
|
||||
class State {
|
||||
// @Snapshotable
|
||||
var count: Int = 0
|
||||
}
|
||||
}
|
||||
`)).toThrow('nested @Observable types are not supported');
|
||||
});
|
||||
|
||||
test('ignores nested observable types that expose no snapshot fields', () => {
|
||||
expect(parseSwift(`
|
||||
enum Namespace {
|
||||
@Observable
|
||||
class State { var transient: Int = 0 }
|
||||
}
|
||||
`)).toEqual([]);
|
||||
});
|
||||
|
||||
test('ignores fields without @Snapshotable marker', () => {
|
||||
@@ -114,10 +256,7 @@ class B {
|
||||
expect(specs.map(s => s.className).sort()).toEqual(['A', 'B']);
|
||||
});
|
||||
|
||||
test('skips fields with computed body braces', () => {
|
||||
// Codex flagged "Properties with computed getters / didSet blocks" as a
|
||||
// failure mode of the fork's regex. We deliberately exclude them here —
|
||||
// computed properties are not snapshot-eligible.
|
||||
test('diagnoses fields with computed body braces', () => {
|
||||
const src = `
|
||||
@Observable
|
||||
class M {
|
||||
@@ -127,9 +266,50 @@ class M {
|
||||
}
|
||||
}
|
||||
`;
|
||||
const specs = parseSwift(src);
|
||||
expect(specs).toHaveLength(1);
|
||||
expect(specs[0]!.fields.map(f => f.name)).toEqual(['snapshotted']);
|
||||
expect(() => parseSwift(src)).toThrow("field 'computed' must be stored and writable");
|
||||
});
|
||||
|
||||
test.each([
|
||||
['let', '// @Snapshotable\n let immutable: Int = 1', 'must be declared var, not let'],
|
||||
['private', '// @Snapshotable\n private var secret: String = ""', 'cannot be private'],
|
||||
['fileprivate', '// @Snapshotable\n fileprivate var secret: String = ""', 'cannot be private'],
|
||||
['private(set)', '// @Snapshotable\n public private(set) var count: Int = 0', 'cannot be private'],
|
||||
['fileprivate(set)', '// @Snapshotable\n fileprivate(set) var count: Int = 0', 'cannot be private'],
|
||||
['inferred type', '// @Snapshotable\n var inferred = 42', 'requires an explicit type annotation'],
|
||||
['multiple bindings', '// @Snapshotable\n var a: Int = 1, b: Int = 2', 'exactly one binding'],
|
||||
['static', '// @Snapshotable\n static var shared: Int = 0', 'must be an instance property'],
|
||||
['nested Optional', '// @Snapshotable\n var nested: String?? = nil', 'cannot use a nested Optional'],
|
||||
['nested Optional in collection', '// @Snapshotable\n var nestedItems: [String??] = []', 'cannot use a nested Optional'],
|
||||
['implicitly unwrapped Optional', '// @Snapshotable\n var legacy: String! = nil', 'cannot use an implicitly unwrapped Optional'],
|
||||
['custom type', '// @Snapshotable\n var custom: CustomValue = .init()', 'uses unsupported snapshot type'],
|
||||
])('diagnoses invalid %s declarations', (_label, declaration, expected) => {
|
||||
expect(() => parseSwift(`
|
||||
@Observable
|
||||
final class InvalidState {
|
||||
${declaration}
|
||||
}
|
||||
`)).toThrow(expected);
|
||||
});
|
||||
|
||||
test('aggregates invalid declaration diagnostics with class and line context', () => {
|
||||
try {
|
||||
parseSwift(`
|
||||
@Observable
|
||||
final class InvalidState {
|
||||
// @Snapshotable
|
||||
let first: Int = 1
|
||||
// @Snapshotable
|
||||
private var second: String = ""
|
||||
}
|
||||
`);
|
||||
throw new Error('expected parseSwift to fail');
|
||||
} catch (error) {
|
||||
expect(error).toBeInstanceOf(AccessorGenerationError);
|
||||
const generationError = error as AccessorGenerationError;
|
||||
expect(generationError.diagnostics).toHaveLength(2);
|
||||
expect(generationError.message).toContain('InvalidState (line 4)');
|
||||
expect(generationError.message).toContain('InvalidState (line 6)');
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
@@ -244,6 +424,68 @@ describe('computeCacheKey', () => {
|
||||
});
|
||||
expect(k1).not.toBe(k2);
|
||||
});
|
||||
|
||||
test('app build provenance invalidates the cache key', () => {
|
||||
const f = join(workDir, 'a.swift');
|
||||
writeFileSync(f, '@Observable class A {}');
|
||||
const shared = {
|
||||
swiftFiles: [f],
|
||||
swiftVersion: '6.0.0',
|
||||
toolGitRev: 'abc',
|
||||
platformTriple: 'darwin-arm64',
|
||||
};
|
||||
expect(computeCacheKey({ ...shared, buildId: '100' })).not.toBe(
|
||||
computeCacheKey({ ...shared, buildId: '101' }),
|
||||
);
|
||||
});
|
||||
|
||||
test('equivalent source content does not depend on its absolute checkout path', () => {
|
||||
const firstDir = join(workDir, 'checkout-a');
|
||||
const secondDir = join(workDir, 'checkout-b');
|
||||
mkdirSync(firstDir);
|
||||
mkdirSync(secondDir);
|
||||
const first = join(firstDir, 'State.swift');
|
||||
const second = join(secondDir, 'State.swift');
|
||||
writeFileSync(first, '@Observable class A {}');
|
||||
writeFileSync(second, '@Observable class A {}');
|
||||
const versioning = { swiftVersion: '6', toolGitRev: 't', platformTriple: 'p' };
|
||||
expect(computeCacheKey({ swiftFiles: [first], ...versioning })).toBe(
|
||||
computeCacheKey({ swiftFiles: [second], ...versioning }),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('computeAccessorHash', () => {
|
||||
const base: AccessorSpec[] = [{
|
||||
className: 'AppState',
|
||||
fields: [
|
||||
{ name: 'count', typeText: 'Int' },
|
||||
{ name: 'nickname', typeText: 'String?' },
|
||||
],
|
||||
}];
|
||||
|
||||
test('is deterministic for the same ordered accessor signatures', () => {
|
||||
expect(computeAccessorHash(base)).toBe(computeAccessorHash(structuredClone(base)));
|
||||
});
|
||||
|
||||
test('changes when field order, name, or type changes', () => {
|
||||
const reordered: AccessorSpec[] = [{
|
||||
className: 'AppState',
|
||||
fields: [...base[0]!.fields].reverse(),
|
||||
}];
|
||||
const renamed: AccessorSpec[] = [{
|
||||
className: 'AppState',
|
||||
fields: [{ name: 'total', typeText: 'Int' }, base[0]!.fields[1]!],
|
||||
}];
|
||||
const retyped: AccessorSpec[] = [{
|
||||
className: 'AppState',
|
||||
fields: [{ name: 'count', typeText: 'Int64' }, base[0]!.fields[1]!],
|
||||
}];
|
||||
const hash = computeAccessorHash(base);
|
||||
expect(computeAccessorHash(reordered)).not.toBe(hash);
|
||||
expect(computeAccessorHash(renamed)).not.toBe(hash);
|
||||
expect(computeAccessorHash(retyped)).not.toBe(hash);
|
||||
});
|
||||
});
|
||||
|
||||
describe('generate', () => {
|
||||
@@ -283,6 +525,35 @@ class AppState {
|
||||
expect(r1.cacheKey).toBe(r2.cacheKey);
|
||||
});
|
||||
|
||||
test('custom nested output subtree cannot poison the second-run cache key', () => {
|
||||
const inputDir = join(workDir, 'src');
|
||||
const outputDir = join(inputDir, 'generated', 'accessors');
|
||||
mkdirSync(inputDir);
|
||||
writeFileSync(join(inputDir, 'state.swift'), '@Observable class A { @Snapshotable var x: Int = 0 }');
|
||||
const cacheRoot = join(workDir, 'cache');
|
||||
|
||||
const r1 = generate({
|
||||
inputDir,
|
||||
outputDir,
|
||||
cacheRoot,
|
||||
swiftVersion: '6',
|
||||
toolGitRev: 't',
|
||||
platformTriple: 'p',
|
||||
});
|
||||
writeFileSync(join(outputDir, 'Ignored.swift'), '@Observable class Poison { @Snapshotable var bad: Int = 1 }');
|
||||
const r2 = generate({
|
||||
inputDir,
|
||||
outputDir,
|
||||
cacheRoot,
|
||||
swiftVersion: '6',
|
||||
toolGitRev: 't',
|
||||
platformTriple: 'p',
|
||||
});
|
||||
|
||||
expect(r2.cacheHit).toBe(true);
|
||||
expect(r2.cacheKey).toBe(r1.cacheKey);
|
||||
});
|
||||
|
||||
test('modifying source invalidates the cache', () => {
|
||||
const inputDir = join(workDir, 'src');
|
||||
mkdirSync(inputDir);
|
||||
@@ -295,6 +566,62 @@ class AppState {
|
||||
expect(r1.cacheKey).not.toBe(r2.cacheKey);
|
||||
expect(r2.cacheHit).toBe(false);
|
||||
});
|
||||
|
||||
test('unmarked source churn changes cache identity but not schema identity', () => {
|
||||
const inputDir = join(workDir, 'src');
|
||||
mkdirSync(inputDir);
|
||||
const state = join(inputDir, 'state.swift');
|
||||
const unrelated = join(inputDir, 'unrelated.swift');
|
||||
writeFileSync(state, '@Observable class A { // @Snapshotable\n var x: Int = 0\n }');
|
||||
writeFileSync(unrelated, 'struct Unrelated { let a = 1 }');
|
||||
const cacheRoot = join(workDir, 'cache');
|
||||
const options = { inputDir, cacheRoot, swiftVersion: '6', toolGitRev: 't', platformTriple: 'p' };
|
||||
const first = generate(options);
|
||||
writeFileSync(unrelated, 'struct Unrelated { let a = 2 }');
|
||||
const second = generate(options);
|
||||
expect(second.cacheKey).not.toBe(first.cacheKey);
|
||||
expect(second.accessorHash).toBe(first.accessorHash);
|
||||
});
|
||||
|
||||
test('buildId changes cannot reuse generated fallback provenance', () => {
|
||||
const inputDir = join(workDir, 'src');
|
||||
mkdirSync(inputDir);
|
||||
writeFileSync(join(inputDir, 'state.swift'), '@Observable class A { @Snapshotable var x: Int = 0 }');
|
||||
const cacheRoot = join(workDir, 'cache');
|
||||
const shared = { inputDir, cacheRoot, swiftVersion: '6', toolGitRev: 't', platformTriple: 'p' };
|
||||
const first = generate({ ...shared, buildId: 'build-100' });
|
||||
const second = generate({ ...shared, buildId: 'build-101' });
|
||||
expect(second.cacheKey).not.toBe(first.cacheKey);
|
||||
expect(second.cacheHit).toBe(false);
|
||||
expect(readFileSync(second.outputPath, 'utf8')).toContain('?? "build-101"');
|
||||
});
|
||||
|
||||
test('CLI exits 4 with actionable diagnostics and no generated output', () => {
|
||||
const inputDir = join(workDir, 'src');
|
||||
const outputDir = join(workDir, 'generated');
|
||||
mkdirSync(inputDir);
|
||||
writeFileSync(join(inputDir, 'state.swift'), `
|
||||
@Observable final class InvalidState {
|
||||
// @Snapshotable
|
||||
private let secret = "nope"
|
||||
}
|
||||
`);
|
||||
const result = spawnSync('bun', [
|
||||
join(import.meta.dir, 'gen-accessors.ts'),
|
||||
'--input', inputDir,
|
||||
'--output', outputDir,
|
||||
], {
|
||||
encoding: 'utf8',
|
||||
env: { ...process.env, GSTACK_IOS_CACHE_ROOT: join(workDir, 'cache') },
|
||||
});
|
||||
expect(result.status).toBe(4);
|
||||
// `let` is diagnosed first; either way the class/property is named and
|
||||
// generation never emits an accessor that will fail in xcodebuild.
|
||||
expect(result.stderr).toContain('InvalidState');
|
||||
expect(result.stderr).toContain("field 'secret' must be declared var, not let");
|
||||
expect(result.stderr).not.toContain('AccessorGenerationError:');
|
||||
expect(existsSync(join(outputDir, 'StateAccessor.swift'))).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('pruneCache', () => {
|
||||
@@ -332,14 +659,395 @@ describe('render', () => {
|
||||
fields: [{ name: 'a', typeText: 'Int' }, { name: 'b', typeText: 'String' }],
|
||||
}];
|
||||
const out = render(specs, 'build-1.2.3', 'hash-abc');
|
||||
expect(out).toContain('public enum AppStateAccessor');
|
||||
expect(out).toContain('enum AppStateAccessor');
|
||||
expect(out).not.toContain('public enum AppStateAccessor');
|
||||
expect(out).toContain('static func register(_ state: AppState)');
|
||||
expect(out).not.toContain('public static func register(_ state: AppState)');
|
||||
expect(out).toContain('key: "a"');
|
||||
expect(out).toContain('key: "b"');
|
||||
expect(out).toContain('buildId: "build-1.2.3"');
|
||||
expect(out).toContain('return .missingKey("a")');
|
||||
expect(out).toContain('return .typeMismatch("b")');
|
||||
expect(out).toContain('guard let restored0 = Self.decodeSnapshotValue(raw0, as: Int.self)');
|
||||
expect(out).toContain('guard let restored1 = Self.decodeSnapshotValue(raw1, as: String.self)');
|
||||
expect(out).toContain('atomicRestore: { keys, apply in');
|
||||
expect(out).toContain('if apply {');
|
||||
expect(out).toContain('state.a = restored0');
|
||||
expect(out).toContain('state.b = restored1');
|
||||
expect(out.indexOf('state.a = restored0')).toBeGreaterThan(out.indexOf('guard let restored1'));
|
||||
expect(out).toContain('guard let typed = Self.decodeSnapshotValue(value, as: Int.self) else { return false }');
|
||||
expect(out).toContain('state.a = typed');
|
||||
expect(out).toContain('return true');
|
||||
expect(out).not.toContain('atomicRestore: { _ in .ok }');
|
||||
expect(out).not.toContain('write: { _ in false }');
|
||||
expect(out).toContain('CFBundleShortVersionString');
|
||||
expect(out).toContain('CFBundleVersion');
|
||||
expect(out).toContain('return shortVersion ?? bundleVersion ?? "build-1.2.3"');
|
||||
expect(out).toContain('accessorHash: "hash-abc"');
|
||||
expect(out).toContain('import DebugBridgeCore');
|
||||
expect(out).not.toContain('import DebugBridge\n');
|
||||
expect(out).toContain('#if DEBUG');
|
||||
expect(out).toContain('#endif');
|
||||
});
|
||||
|
||||
test('emits explicit NSNull round-trip handling for Optional fields', () => {
|
||||
const out = render([{
|
||||
className: 'AppState',
|
||||
fields: [
|
||||
{ name: 'nickname', typeText: 'String?' },
|
||||
{ name: 'selection', typeText: 'Optional<Int>' },
|
||||
],
|
||||
}], 'build', 'schema');
|
||||
|
||||
expect(out).toContain('let restored0: String?');
|
||||
expect(out).toContain('if raw0 is NSNull');
|
||||
expect(out).toContain('else if let typed = Self.decodeSnapshotValue(raw0, as: String.self)');
|
||||
expect(out).toContain('let restored1: Optional<Int>');
|
||||
expect(out).toContain('else if let typed = Self.decodeSnapshotValue(raw1, as: Int.self)');
|
||||
expect(out).toContain('guard let value = state.nickname else { return NSNull() }');
|
||||
expect(out).toContain('if value is NSNull');
|
||||
expect(out).toContain('state.nickname = nil');
|
||||
expect(out).not.toContain('value as? String?');
|
||||
});
|
||||
|
||||
test('rejects duplicate snapshot keys across observable models', () => {
|
||||
expect(() => render([
|
||||
{ className: 'FirstState', fields: [{ name: 'count', typeText: 'Int' }] },
|
||||
{ className: 'SecondState', fields: [{ name: 'count', typeText: 'Int' }] },
|
||||
], 'build', 'schema')).toThrow("snapshot key 'count' is declared by both FirstState and SecondState");
|
||||
});
|
||||
|
||||
test('typechecks beside an internal @Observable app state using a comment marker', () => {
|
||||
if (spawnSync('swiftc', ['--version'], { encoding: 'utf8' }).status !== 0) return;
|
||||
|
||||
const coreSource = join(workDir, 'DebugBridgeCore.swift');
|
||||
const coreModule = join(workDir, 'DebugBridgeCore.swiftmodule');
|
||||
writeFileSync(coreSource, `
|
||||
public typealias JSONDict = [String: Any]
|
||||
|
||||
@MainActor
|
||||
public final class StateServer {
|
||||
public static let shared = StateServer()
|
||||
public enum RestoreResult {
|
||||
case ok
|
||||
case missingKey(String)
|
||||
case typeMismatch(String)
|
||||
}
|
||||
private init() {}
|
||||
public func register(
|
||||
buildId: String,
|
||||
accessorHash: String,
|
||||
atomicRestore: @escaping (JSONDict, Bool) -> RestoreResult
|
||||
) {}
|
||||
public func registerAccessor(
|
||||
key: String,
|
||||
type: String,
|
||||
read: @escaping () -> Any?,
|
||||
write: @escaping (Any) -> Bool
|
||||
) {}
|
||||
}
|
||||
`);
|
||||
const emitModule = spawnSync('swiftc', [
|
||||
'-emit-module',
|
||||
'-parse-as-library',
|
||||
'-module-name', 'DebugBridgeCore',
|
||||
coreSource,
|
||||
'-emit-module-path', coreModule,
|
||||
], { encoding: 'utf8' });
|
||||
if (emitModule.status !== 0) {
|
||||
throw new Error(`failed to build DebugBridgeCore test stub:\n${emitModule.stderr}`);
|
||||
}
|
||||
|
||||
const appSource = join(workDir, 'AppState.swift');
|
||||
writeFileSync(appSource, `import Observation
|
||||
|
||||
@Observable
|
||||
final class AppState {
|
||||
// @Snapshotable
|
||||
var counter: Int = 0
|
||||
}
|
||||
|
||||
${render([{
|
||||
className: 'AppState',
|
||||
fields: [{ name: 'counter', typeText: 'Int' }],
|
||||
}], 'build-test', 'hash-test')}`);
|
||||
const typecheck = spawnSync('swiftc', [
|
||||
'-typecheck',
|
||||
'-D', 'DEBUG',
|
||||
'-I', workDir,
|
||||
appSource,
|
||||
], { encoding: 'utf8' });
|
||||
if (typecheck.status !== 0) {
|
||||
throw new Error(`generated accessor failed Swift type checking:\n${typecheck.stderr}`);
|
||||
}
|
||||
});
|
||||
|
||||
test('strict JSON typing and cross-model validate-before-apply restore run correctly', () => {
|
||||
if (process.platform !== 'darwin') return;
|
||||
if (spawnSync('swiftc', ['--version'], { encoding: 'utf8' }).status !== 0) return;
|
||||
|
||||
const coreSource = join(workDir, 'DebugBridgeCore.swift');
|
||||
const coreModule = join(workDir, 'DebugBridgeCore.swiftmodule');
|
||||
const coreLibrary = join(workDir, 'libDebugBridgeCore.dylib');
|
||||
writeFileSync(coreSource, `
|
||||
public typealias JSONDict = [String: Any]
|
||||
|
||||
@MainActor
|
||||
public final class StateServer {
|
||||
public typealias Restore = (JSONDict, Bool) -> RestoreResult
|
||||
public enum RestoreResult { case ok, missingKey(String), typeMismatch(String) }
|
||||
public static let shared = StateServer()
|
||||
public var restores: [Restore] = []
|
||||
public var reads: [String: () -> Any?] = [:]
|
||||
public var writes: [String: (Any) -> Bool] = [:]
|
||||
private init() {}
|
||||
public func register(buildId: String, accessorHash: String, atomicRestore: @escaping Restore) {
|
||||
restores.append(atomicRestore)
|
||||
}
|
||||
public func registerAccessor(
|
||||
key: String,
|
||||
type: String,
|
||||
read: @escaping () -> Any?,
|
||||
write: @escaping (Any) -> Bool
|
||||
) {
|
||||
reads[key] = read
|
||||
writes[key] = write
|
||||
}
|
||||
public func restoreAll(_ keys: JSONDict) -> RestoreResult {
|
||||
for restore in restores {
|
||||
let result = restore(keys, false)
|
||||
guard case .ok = result else { return result }
|
||||
}
|
||||
for restore in restores {
|
||||
let result = restore(keys, true)
|
||||
guard case .ok = result else { return result }
|
||||
}
|
||||
return .ok
|
||||
}
|
||||
}
|
||||
`);
|
||||
const emitCore = spawnSync('swiftc', [
|
||||
'-emit-library', '-emit-module', '-parse-as-library',
|
||||
'-module-name', 'DebugBridgeCore', coreSource,
|
||||
'-emit-module-path', coreModule,
|
||||
'-o', coreLibrary,
|
||||
], { encoding: 'utf8' });
|
||||
if (emitCore.status !== 0) throw new Error(`failed to build runtime stub:\n${emitCore.stderr}`);
|
||||
|
||||
const appSource = join(workDir, 'OptionalRoundTrip.swift');
|
||||
writeFileSync(appSource, `
|
||||
import Foundation
|
||||
import Observation
|
||||
import DebugBridgeCore
|
||||
|
||||
@Observable
|
||||
final class AppState {
|
||||
// @Snapshotable
|
||||
var nickname: String? = nil
|
||||
// @Snapshotable
|
||||
var count: Int = 1
|
||||
}
|
||||
|
||||
@Observable
|
||||
final class FeatureState {
|
||||
// @Snapshotable
|
||||
var enabled: Bool = false
|
||||
}
|
||||
|
||||
${render([
|
||||
{
|
||||
className: 'AppState',
|
||||
fields: [
|
||||
{ name: 'nickname', typeText: 'String?' },
|
||||
{ name: 'count', typeText: 'Int' },
|
||||
],
|
||||
},
|
||||
{
|
||||
className: 'FeatureState',
|
||||
fields: [{ name: 'enabled', typeText: 'Bool' }],
|
||||
},
|
||||
], 'fallback-build', 'schema-hash')}
|
||||
|
||||
@main
|
||||
struct Runner {
|
||||
@MainActor static func main() {
|
||||
let state = AppState()
|
||||
let feature = FeatureState()
|
||||
AppStateAccessor.register(state)
|
||||
FeatureStateAccessor.register(feature)
|
||||
guard StateServer.shared.reads["nickname"]?() is NSNull else { fatalError("nil read") }
|
||||
guard StateServer.shared.writes["nickname"]?("Ada") == true, state.nickname == "Ada" else {
|
||||
fatalError("optional write")
|
||||
}
|
||||
guard StateServer.shared.writes["nickname"]?(NSNull()) == true, state.nickname == nil else {
|
||||
fatalError("null write")
|
||||
}
|
||||
guard StateServer.shared.writes["count"]?(true) == false, state.count == 1 else {
|
||||
fatalError("boolean must not coerce to integer")
|
||||
}
|
||||
guard StateServer.shared.writes["enabled"]?(1) == false, feature.enabled == false else {
|
||||
fatalError("integer must not coerce to boolean")
|
||||
}
|
||||
let valid = try! JSONSerialization.jsonObject(
|
||||
with: Data(#"{"nickname":"Grace","count":7,"enabled":true}"#.utf8)
|
||||
) as! JSONDict
|
||||
switch StateServer.shared.restoreAll(valid) {
|
||||
case .ok: break
|
||||
default: fatalError("valid restore")
|
||||
}
|
||||
guard state.nickname == "Grace", state.count == 7, feature.enabled else { fatalError("restore values") }
|
||||
switch StateServer.shared.restoreAll(["nickname": NSNull(), "count": 8, "enabled": false]) {
|
||||
case .ok: break
|
||||
default: fatalError("null restore")
|
||||
}
|
||||
guard state.nickname == nil, state.count == 8, !feature.enabled else { fatalError("null restore values") }
|
||||
state.nickname = "unchanged"
|
||||
state.count = 9
|
||||
feature.enabled = false
|
||||
switch StateServer.shared.restoreAll(["nickname": "would-partially-apply", "count": 10, "enabled": 1]) {
|
||||
case .typeMismatch("enabled"): break
|
||||
default: fatalError("expected mismatch")
|
||||
}
|
||||
guard state.nickname == "unchanged", state.count == 9, !feature.enabled else { fatalError("cross-model partial mutation") }
|
||||
}
|
||||
}
|
||||
`);
|
||||
const executable = join(workDir, 'optional-round-trip');
|
||||
const compile = spawnSync('swiftc', [
|
||||
'-D', 'DEBUG', '-I', workDir, '-L', workDir, '-lDebugBridgeCore',
|
||||
'-parse-as-library', appSource, '-o', executable,
|
||||
], { encoding: 'utf8' });
|
||||
if (compile.status !== 0) throw new Error(`generated Optional accessor failed compilation:\n${compile.stderr}`);
|
||||
const run = spawnSync(executable, [], {
|
||||
encoding: 'utf8',
|
||||
env: { ...process.env, DYLD_LIBRARY_PATH: workDir },
|
||||
});
|
||||
if (run.status !== 0) throw new Error(`generated Optional accessor failed at runtime:\n${run.stderr}`);
|
||||
});
|
||||
});
|
||||
|
||||
describe('SwiftSyntax generator parity', () => {
|
||||
test('isolates canonical markers and rejects inaccessible fields', () => {
|
||||
if (process.platform !== 'darwin') return;
|
||||
if (spawnSync('swift', ['--version'], { encoding: 'utf8' }).status !== 0) return;
|
||||
|
||||
const packageDir = join(import.meta.dir, 'gen-accessors-tool');
|
||||
const inputDir = join(workDir, 'swift-syntax-input');
|
||||
const outputDir = join(workDir, 'swift-syntax-output');
|
||||
const cacheRoot = join(workDir, 'swift-syntax-cache');
|
||||
mkdirSync(inputDir);
|
||||
writeFileSync(join(inputDir, 'State.swift'), `
|
||||
import Observation
|
||||
@Observable
|
||||
final class ToolState {
|
||||
let documentation = """
|
||||
// @Snapshotable
|
||||
var stringLeak: String = "no"
|
||||
"""
|
||||
/* // @Snapshotable */
|
||||
var blockLeak: Int = 1
|
||||
var trailingLeak: Int = 2 // @Snapshotable
|
||||
// prose about @Snapshotable must not opt in
|
||||
var proseLeak: Int = 3
|
||||
// @Snapshotable
|
||||
var nickname: String? = nil
|
||||
// @Snapshotable
|
||||
var names:
|
||||
[String]
|
||||
= []
|
||||
// @Snapshotable
|
||||
var count: Int = 0
|
||||
// @Snapshotable
|
||||
var enabled: Bool = false
|
||||
}
|
||||
`);
|
||||
const env = {
|
||||
...process.env,
|
||||
GSTACK_IOS_CACHE_ROOT: cacheRoot,
|
||||
APP_BUILD_ID: 'syntax-test-build',
|
||||
GEN_ACCESSORS_REV: 'syntax-test-v5',
|
||||
};
|
||||
const run = spawnSync('swift', [
|
||||
'run', '--package-path', packageDir, 'gen-accessors',
|
||||
'--input', inputDir, '--output', outputDir,
|
||||
], { encoding: 'utf8', env, timeout: 180_000 });
|
||||
if (run.status !== 0) throw new Error(`SwiftSyntax generator failed:\n${run.stderr}`);
|
||||
const output = readFileSync(join(outputDir, 'StateAccessor.swift'), 'utf8');
|
||||
expect(output).toContain('key: "nickname"');
|
||||
expect(output).toContain('key: "names"');
|
||||
expect(output).toContain('key: "count"');
|
||||
expect(output).toContain('key: "enabled"');
|
||||
expect(output).toContain('_GStackDebugBridgeSnapshotJSON.decode(raw0');
|
||||
expect(output).toContain('atomicRestore: { keys, apply in');
|
||||
expect(output).toContain('if apply {');
|
||||
expect(output).not.toMatch(/raw\d+ as\?/);
|
||||
expect(output).toContain('CFBundleShortVersionString');
|
||||
expect(output).toContain(`accessorHash: "${computeAccessorHash([{
|
||||
className: 'ToolState',
|
||||
fields: [
|
||||
{ name: 'nickname', typeText: 'String?' },
|
||||
{ name: 'names', typeText: '[String]' },
|
||||
{ name: 'count', typeText: 'Int' },
|
||||
{ name: 'enabled', typeText: 'Bool' },
|
||||
],
|
||||
}])}"`);
|
||||
expect(output).not.toContain('key: "stringLeak"');
|
||||
expect(output).not.toContain('key: "blockLeak"');
|
||||
expect(output).not.toContain('key: "trailingLeak"');
|
||||
expect(output).not.toContain('key: "proseLeak"');
|
||||
|
||||
const invalidInput = join(workDir, 'swift-syntax-invalid');
|
||||
const invalidOutput = join(workDir, 'swift-syntax-invalid-output');
|
||||
mkdirSync(invalidInput);
|
||||
writeFileSync(join(invalidInput, 'Invalid.swift'), `
|
||||
import Observation
|
||||
@Observable
|
||||
final class InvalidState {
|
||||
// @Snapshotable
|
||||
public private(set) var token: String = "secret"
|
||||
// @Snapshotable
|
||||
let immutable: Int = 1
|
||||
// @Snapshotable
|
||||
var inferred = 2
|
||||
// @Snapshotable
|
||||
var legacy: String! = nil
|
||||
// @Snapshotable
|
||||
var custom: Date = .now
|
||||
}
|
||||
|
||||
enum Namespace {
|
||||
@Observable
|
||||
final class NestedState {
|
||||
// @Snapshotable
|
||||
var nestedValue: Int = 0
|
||||
}
|
||||
}
|
||||
|
||||
@Observable
|
||||
final class FirstState {
|
||||
// @Snapshotable
|
||||
var shared: String = "first"
|
||||
}
|
||||
|
||||
@Observable
|
||||
final class DuplicateState {
|
||||
// @Snapshotable
|
||||
var shared: String = "duplicate"
|
||||
}
|
||||
`);
|
||||
const invalid = spawnSync('swift', [
|
||||
'run', '--package-path', packageDir, 'gen-accessors',
|
||||
'--input', invalidInput, '--output', invalidOutput,
|
||||
], { encoding: 'utf8', env, timeout: 180_000 });
|
||||
expect(invalid.status).toBe(4);
|
||||
expect(invalid.stderr).toContain('InvalidState.token cannot be private');
|
||||
expect(invalid.stderr).toContain('InvalidState.immutable must be declared var, not let');
|
||||
expect(invalid.stderr).toContain('InvalidState.inferred requires an explicit type annotation');
|
||||
expect(invalid.stderr).toContain('InvalidState.legacy cannot use an implicitly unwrapped Optional type');
|
||||
expect(invalid.stderr).toContain("InvalidState.custom uses unsupported non-JSON snapshot type 'Date'");
|
||||
expect(invalid.stderr).toContain('nested @Observable class NestedState');
|
||||
expect(invalid.stderr).toContain("snapshot key 'shared' is declared by both FirstState and DuplicateState");
|
||||
expect(existsSync(join(invalidOutput, 'StateAccessor.swift'))).toBe(false);
|
||||
}, 180_000);
|
||||
});
|
||||
|
||||
describe('collectSwiftFiles', () => {
|
||||
@@ -355,4 +1063,17 @@ describe('collectSwiftFiles', () => {
|
||||
const files = collectSwiftFiles(workDir);
|
||||
expect(files.sort()).toEqual([a, b].sort());
|
||||
});
|
||||
|
||||
test('excludes the configured output subtree and every StateAccessor.swift', () => {
|
||||
const source = join(workDir, 'App.swift');
|
||||
const staleAccessor = join(workDir, 'old', 'StateAccessor.swift');
|
||||
const outputDir = join(workDir, 'custom-output');
|
||||
mkdirSync(join(workDir, 'old'));
|
||||
mkdirSync(outputDir);
|
||||
writeFileSync(source, 'struct App {}');
|
||||
writeFileSync(staleAccessor, '// stale generated output');
|
||||
writeFileSync(join(outputDir, 'Poison.swift'), '// must not be scanned');
|
||||
|
||||
expect(collectSwiftFiles(workDir, { outputDir })).toEqual([source]);
|
||||
});
|
||||
});
|
||||
|
||||
+659
-89
@@ -5,15 +5,16 @@
|
||||
// first time. Also exercised by tests so we can verify the cache + parse
|
||||
// behavior without a Swift toolchain.
|
||||
//
|
||||
// The TS port uses a stricter regex than the fork's original — it understands:
|
||||
// The TS fast path uses a lightweight Swift lexical scanner — it understands:
|
||||
// - @Observable class declarations
|
||||
// - @Snapshotable property markers (only marked fields are exported)
|
||||
// - `// @Snapshotable` property markers (only marked fields are exported)
|
||||
// - Legacy @Snapshotable attributes for existing integrations
|
||||
// - Multi-line type signatures (collapses whitespace before matching)
|
||||
// - Generic type parameters (matched as opaque text inside the type)
|
||||
// - JSON-native generic arrays and String-keyed dictionaries
|
||||
//
|
||||
// What it does NOT handle (deferred to the SwiftPM tool):
|
||||
// - Computed properties with bodies (regex can mis-parse braces)
|
||||
// - Property wrappers other than @Snapshotable
|
||||
// Invalid marked declarations (computed/immutable/inaccessible/untyped,
|
||||
// nested, duplicate-keyed, or non-JSON) fail generation instead of producing
|
||||
// Swift that only fails later in xcodebuild or at snapshot time.
|
||||
//
|
||||
// Composite cache key (codex-flagged): swift_version || tool_git_rev ||
|
||||
// platform_triple || source_content_hash. Source-only hash misses generator
|
||||
@@ -35,6 +36,16 @@ export interface AccessorSpec {
|
||||
fields: AccessorField[];
|
||||
}
|
||||
|
||||
export class AccessorGenerationError extends Error {
|
||||
readonly diagnostics: string[];
|
||||
|
||||
constructor(diagnostics: string[]) {
|
||||
super(`gen-accessors: invalid @Snapshotable declaration(s):\n${diagnostics.map(d => ` - ${d}`).join('\n')}`);
|
||||
this.name = 'AccessorGenerationError';
|
||||
this.diagnostics = diagnostics;
|
||||
}
|
||||
}
|
||||
|
||||
export interface GenInputs {
|
||||
inputDir: string;
|
||||
outputDir?: string;
|
||||
@@ -48,56 +59,105 @@ export interface GenInputs {
|
||||
export interface GenResult {
|
||||
outputPath: string;
|
||||
cacheKey: string;
|
||||
accessorHash: string;
|
||||
specs: AccessorSpec[];
|
||||
cacheHit: boolean;
|
||||
}
|
||||
|
||||
const FALLBACK_PLATFORM = process.platform === 'darwin' ? 'darwin-arm64' : `${process.platform}-${process.arch}`;
|
||||
const GENERATOR_FORMAT_VERSION = 'accessor-generator-v5';
|
||||
|
||||
export function collectSwiftFiles(dir: string, opts: { excludeGenerated?: boolean } = {}): string[] {
|
||||
const JSON_SCALAR_TYPES = new Set([
|
||||
'String',
|
||||
'Bool',
|
||||
'Int', 'Int8', 'Int16', 'Int32', 'Int64',
|
||||
'UInt', 'UInt8', 'UInt16', 'UInt32', 'UInt64',
|
||||
'Float', 'Double', 'CGFloat',
|
||||
]);
|
||||
|
||||
export function collectSwiftFiles(
|
||||
dir: string,
|
||||
opts: { excludeGenerated?: boolean; outputDir?: string } = {},
|
||||
): string[] {
|
||||
const out: string[] = [];
|
||||
const excludeGenerated = opts.excludeGenerated ?? true;
|
||||
for (const name of readdirSync(dir)) {
|
||||
const full = join(dir, name);
|
||||
const s = statSync(full);
|
||||
if (s.isDirectory()) {
|
||||
// Skip generated output dir (when it lives under the input dir)
|
||||
if (excludeGenerated && name === 'DebugBridgeGenerated') continue;
|
||||
out.push(...collectSwiftFiles(full, opts));
|
||||
} else if (name.endsWith('.swift')) {
|
||||
// Skip the codegen output file. Otherwise the second run picks it up,
|
||||
// changes the cache key, and the cache never hits.
|
||||
if (excludeGenerated && name === 'StateAccessor.swift') continue;
|
||||
out.push(full);
|
||||
const root = resolve(dir);
|
||||
const outputDir = opts.outputDir ? resolve(opts.outputDir) : undefined;
|
||||
|
||||
function walk(currentDir: string): void {
|
||||
for (const name of readdirSync(currentDir)) {
|
||||
const full = join(currentDir, name);
|
||||
const s = statSync(full);
|
||||
if (s.isDirectory()) {
|
||||
// The generated subtree must never participate in its own cache key.
|
||||
// Keep the well-known-name guard for direct collectSwiftFiles callers,
|
||||
// and use the actual --output path when generate() supplies one.
|
||||
const isOutputSubtree = outputDir !== undefined
|
||||
&& outputDir !== root
|
||||
&& resolve(full) === outputDir;
|
||||
if (excludeGenerated && (name === 'DebugBridgeGenerated' || isOutputSubtree)) continue;
|
||||
walk(full);
|
||||
} else if (name.endsWith('.swift')) {
|
||||
// Skip generated accessor files wherever they live. Otherwise moving
|
||||
// an old copy outside the output directory poisons the next cache key.
|
||||
if (excludeGenerated && name === 'StateAccessor.swift') continue;
|
||||
out.push(full);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
walk(root);
|
||||
return out.sort();
|
||||
}
|
||||
|
||||
export function parseSwift(source: string): AccessorSpec[] {
|
||||
const specs: AccessorSpec[] = [];
|
||||
const diagnostics: string[] = [];
|
||||
const masked = maskSwiftSource(source);
|
||||
// Find `@Observable\n(public )?(final )?class <Name>` followed by a brace
|
||||
// block. We then scan inside that block for @Snapshotable fields.
|
||||
const classPattern = /@Observable\s*(?:(?:public|internal|fileprivate|private)\s+)?(?:final\s+)?class\s+(\w+)[^{]*\{/g;
|
||||
|
||||
let match: RegExpExecArray | null;
|
||||
while ((match = classPattern.exec(source)) !== null) {
|
||||
for (const match of masked.matchAll(classPattern)) {
|
||||
const className = match[1]!;
|
||||
const startIdx = classPattern.lastIndex;
|
||||
const endIdx = findMatchingBrace(source, startIdx - 1);
|
||||
const matchOffset = match.index!;
|
||||
const openBraceOffset = matchOffset + match[0].lastIndexOf('{');
|
||||
const startIdx = openBraceOffset + 1;
|
||||
const endIdx = findMatchingBrace(masked, startIdx - 1);
|
||||
if (endIdx === -1) continue;
|
||||
const body = source.slice(startIdx, endIdx);
|
||||
const body = masked.slice(startIdx, endIdx);
|
||||
|
||||
const fields = parseFields(body);
|
||||
const parsed = parseFields(body, source, startIdx, className);
|
||||
if (braceDepthAt(masked, matchOffset) !== 0) {
|
||||
if (parsed.fields.length > 0 || parsed.diagnostics.length > 0) {
|
||||
const line = source.slice(0, matchOffset).split(/\r?\n/).length;
|
||||
diagnostics.push(`${className} (line ${line}): nested @Observable types are not supported; move the type to file scope`);
|
||||
}
|
||||
continue;
|
||||
}
|
||||
diagnostics.push(...parsed.diagnostics);
|
||||
const fields = parsed.fields;
|
||||
if (fields.length > 0) {
|
||||
specs.push({ className, fields });
|
||||
}
|
||||
}
|
||||
|
||||
if (diagnostics.length > 0) throw new AccessorGenerationError(diagnostics);
|
||||
return specs;
|
||||
}
|
||||
|
||||
function braceDepthAt(masked: string, offset: number): number {
|
||||
let depth = 0;
|
||||
for (let i = 0; i < offset; i++) {
|
||||
if (masked[i] === '{') depth++;
|
||||
else if (masked[i] === '}') depth = Math.max(0, depth - 1);
|
||||
}
|
||||
return depth;
|
||||
}
|
||||
|
||||
function findMatchingBrace(s: string, openIdx: number): number {
|
||||
// openIdx points at '{'. Return idx of matching '}', or -1.
|
||||
// Strings and comments have already been blanked by maskSwiftSource, so
|
||||
// braces here are syntax rather than prose or literal content.
|
||||
let depth = 0;
|
||||
for (let i = openIdx; i < s.length; i++) {
|
||||
const c = s[i];
|
||||
@@ -105,48 +165,305 @@ function findMatchingBrace(s: string, openIdx: number): number {
|
||||
else if (c === '}') {
|
||||
depth--;
|
||||
if (depth === 0) return i;
|
||||
} else if (c === '"' || c === "'") {
|
||||
// skip string literal
|
||||
const quote = c;
|
||||
i++;
|
||||
while (i < s.length && s[i] !== quote) {
|
||||
if (s[i] === '\\') i++;
|
||||
i++;
|
||||
}
|
||||
} else if (c === '/' && s[i + 1] === '/') {
|
||||
// skip line comment
|
||||
while (i < s.length && s[i] !== '\n') i++;
|
||||
} else if (c === '/' && s[i + 1] === '*') {
|
||||
i += 2;
|
||||
while (i < s.length - 1 && !(s[i] === '*' && s[i + 1] === '/')) i++;
|
||||
i++;
|
||||
}
|
||||
}
|
||||
return -1;
|
||||
}
|
||||
|
||||
function parseFields(body: string): AccessorField[] {
|
||||
// Look for @Snapshotable followed by var/let declarations. Allow attribute
|
||||
// ordering: `@Snapshotable var name: Type` OR `@Snapshotable\n var name: Type`.
|
||||
// Multi-line types are handled by greedy non-newline match in the type, but
|
||||
// we collapse adjacent whitespace first to avoid false negatives.
|
||||
const normalized = body.replace(/[\t ]*\r?\n[\t ]*/g, ' ');
|
||||
const fieldPattern = /@Snapshotable\s+(?:(?:public|internal|fileprivate|private)\s+)?(?:var|let)\s+(\w+)\s*:\s*([^={]+?)(?=\s*(?:=|\{|@Snapshotable|\bvar\b|\blet\b|\bfunc\b|\}|$))/g;
|
||||
const fields: AccessorField[] = [];
|
||||
let m: RegExpExecArray | null;
|
||||
while ((m = fieldPattern.exec(normalized)) !== null) {
|
||||
// Codex catch: skip fields that have a computed body (`{ get ... }` or
|
||||
// `{ didSet ... }` after the type). The match boundary stops before `{`,
|
||||
// so we peek at what comes after the type in the original body.
|
||||
const afterMatchIdx = m.index + m[0].length;
|
||||
const afterMatch = normalized.slice(afterMatchIdx, afterMatchIdx + 4).trim();
|
||||
// If the next non-space character is `{`, this is a computed property.
|
||||
// We're conservative: snapshot-eligible fields must be stored properties
|
||||
// (initialized with `=` or just declared).
|
||||
if (afterMatch.startsWith('{')) continue;
|
||||
fields.push({ name: m[1]!, typeText: m[2]!.trim() });
|
||||
/**
|
||||
* Blank comments and string literals while preserving byte offsets/newlines.
|
||||
* A canonical standalone `// @Snapshotable` comment is rewritten to the
|
||||
* equivalent attribute token. This is intentionally lexical rather than a
|
||||
* whole-file regexp: markers inside nested block comments, normal/triple/raw
|
||||
* strings, trailing comments, and prose comments must never opt a field in.
|
||||
*/
|
||||
function maskSwiftSource(source: string): string {
|
||||
const out = source.split('');
|
||||
|
||||
const blank = (start: number, end: number): void => {
|
||||
for (let j = start; j < end; j++) {
|
||||
if (out[j] !== '\n' && out[j] !== '\r') out[j] = ' ';
|
||||
}
|
||||
};
|
||||
|
||||
let i = 0;
|
||||
while (i < source.length) {
|
||||
if (source[i] === '/' && source[i + 1] === '/') {
|
||||
let end = i + 2;
|
||||
while (end < source.length && source[end] !== '\n' && source[end] !== '\r') end++;
|
||||
const lineStart = source.lastIndexOf('\n', i - 1) + 1;
|
||||
const standalone = source.slice(lineStart, i).trim().length === 0;
|
||||
const isMarker = standalone && source.slice(i + 2, end).trim() === '@Snapshotable';
|
||||
blank(i, end);
|
||||
if (isMarker) {
|
||||
const marker = '@Snapshotable';
|
||||
for (let j = 0; j < marker.length; j++) out[i + j] = marker[j]!;
|
||||
}
|
||||
i = end;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (source[i] === '/' && source[i + 1] === '*') {
|
||||
const start = i;
|
||||
i += 2;
|
||||
let depth = 1;
|
||||
while (i < source.length && depth > 0) {
|
||||
if (source[i] === '/' && source[i + 1] === '*') {
|
||||
depth++;
|
||||
i += 2;
|
||||
} else if (source[i] === '*' && source[i + 1] === '/') {
|
||||
depth--;
|
||||
i += 2;
|
||||
} else {
|
||||
i++;
|
||||
}
|
||||
}
|
||||
blank(start, i);
|
||||
continue;
|
||||
}
|
||||
|
||||
// Swift strings may be ordinary, multiline, or raw (`#"..."#` and
|
||||
// `#"""..."""#`). Mask the entire literal, including interpolation;
|
||||
// declarations cannot legally originate inside a literal.
|
||||
let hashCount = 0;
|
||||
while (source[i + hashCount] === '#') hashCount++;
|
||||
const quoteIdx = i + hashCount;
|
||||
if (source[quoteIdx] === '"') {
|
||||
const start = i;
|
||||
const triple = source.slice(quoteIdx, quoteIdx + 3) === '"""';
|
||||
const quoteCount = triple ? 3 : 1;
|
||||
i = quoteIdx + quoteCount;
|
||||
while (i < source.length) {
|
||||
if (hashCount === 0 && source[i] === '\\') {
|
||||
i += 2;
|
||||
continue;
|
||||
}
|
||||
const quoteRun = source.slice(i, i + quoteCount) === '"'.repeat(quoteCount);
|
||||
const hashesMatch = source.slice(i + quoteCount, i + quoteCount + hashCount) === '#'.repeat(hashCount);
|
||||
if (quoteRun && hashesMatch) {
|
||||
i += quoteCount + hashCount;
|
||||
break;
|
||||
}
|
||||
i++;
|
||||
}
|
||||
blank(start, i);
|
||||
continue;
|
||||
}
|
||||
|
||||
i++;
|
||||
}
|
||||
return fields;
|
||||
return out.join('');
|
||||
}
|
||||
|
||||
const DECL_MODIFIERS = new Set([
|
||||
'public', 'internal', 'package', 'open', 'private', 'fileprivate',
|
||||
'final', 'static', 'class', 'lazy', 'weak', 'unowned', 'override',
|
||||
'nonisolated', 'isolated', 'borrowing', 'consuming',
|
||||
]);
|
||||
|
||||
function parseFields(
|
||||
body: string,
|
||||
fullSource: string,
|
||||
bodyOffset: number,
|
||||
className: string,
|
||||
): { fields: AccessorField[]; diagnostics: string[] } {
|
||||
const fields: AccessorField[] = [];
|
||||
const diagnostics: string[] = [];
|
||||
let braceDepth = 0;
|
||||
|
||||
const lineFor = (localOffset: number): number => {
|
||||
const absolute = bodyOffset + localOffset;
|
||||
let line = 1;
|
||||
for (let j = 0; j < absolute; j++) if (fullSource[j] === '\n') line++;
|
||||
return line;
|
||||
};
|
||||
const fail = (offset: number, message: string): void => {
|
||||
diagnostics.push(`${className} (line ${lineFor(offset)}): ${message}`);
|
||||
};
|
||||
const skipWhitespace = (start: number): number => {
|
||||
let at = start;
|
||||
while (at < body.length && /\s/.test(body[at]!)) at++;
|
||||
return at;
|
||||
};
|
||||
const identifierAt = (start: number): { text: string; end: number } | undefined => {
|
||||
const m = /^[A-Za-z_]\w*/.exec(body.slice(start));
|
||||
return m ? { text: m[0], end: start + m[0].length } : undefined;
|
||||
};
|
||||
const skipBalancedParens = (start: number): number => {
|
||||
if (body[start] !== '(') return start;
|
||||
let depth = 0;
|
||||
for (let at = start; at < body.length; at++) {
|
||||
if (body[at] === '(') depth++;
|
||||
else if (body[at] === ')' && --depth === 0) return at + 1;
|
||||
}
|
||||
return body.length;
|
||||
};
|
||||
|
||||
for (let i = 0; i < body.length; i++) {
|
||||
if (body[i] === '{') {
|
||||
braceDepth++;
|
||||
continue;
|
||||
}
|
||||
if (body[i] === '}') {
|
||||
braceDepth--;
|
||||
continue;
|
||||
}
|
||||
if (braceDepth !== 0 || !body.startsWith('@Snapshotable', i)) continue;
|
||||
const before = i === 0 ? '' : body[i - 1]!;
|
||||
const after = body[i + '@Snapshotable'.length] ?? '';
|
||||
if (/\w/.test(before) || /\w/.test(after)) continue;
|
||||
|
||||
const markerOffset = i;
|
||||
let at = skipWhitespace(i + '@Snapshotable'.length);
|
||||
const modifiers: string[] = [];
|
||||
let bindingKind: 'var' | 'let' | undefined;
|
||||
|
||||
// Permit other Swift attributes between the marker and declaration. They
|
||||
// remain the compiler's responsibility; this scanner only owns the
|
||||
// snapshot contract. Parenthesized attribute arguments are skipped.
|
||||
while (body[at] === '@') {
|
||||
const attribute = identifierAt(at + 1);
|
||||
if (!attribute) break;
|
||||
at = skipWhitespace(attribute.end);
|
||||
if (body[at] === '(') at = skipBalancedParens(at);
|
||||
at = skipWhitespace(at);
|
||||
}
|
||||
|
||||
while (at < body.length) {
|
||||
const token = identifierAt(at);
|
||||
if (!token) break;
|
||||
if (token.text === 'var' || token.text === 'let') {
|
||||
bindingKind = token.text;
|
||||
at = token.end;
|
||||
break;
|
||||
}
|
||||
if (!DECL_MODIFIERS.has(token.text)) break;
|
||||
let modifier = token.text;
|
||||
at = skipWhitespace(token.end);
|
||||
if (body[at] === '(') {
|
||||
const end = skipBalancedParens(at);
|
||||
modifier += body.slice(at, end).replace(/\s+/g, '');
|
||||
at = skipWhitespace(end);
|
||||
}
|
||||
modifiers.push(modifier);
|
||||
}
|
||||
|
||||
if (!bindingKind) {
|
||||
fail(markerOffset, '@Snapshotable must immediately precede a stored property declaration');
|
||||
continue;
|
||||
}
|
||||
|
||||
at = skipWhitespace(at);
|
||||
const identifier = identifierAt(at);
|
||||
const fieldName = identifier?.text ?? '<unknown>';
|
||||
if (!identifier) {
|
||||
fail(markerOffset, '@Snapshotable only supports a single identifier binding');
|
||||
continue;
|
||||
}
|
||||
at = skipWhitespace(identifier.end);
|
||||
|
||||
if (bindingKind === 'let') {
|
||||
fail(markerOffset, `@Snapshotable field '${fieldName}' must be declared var, not let`);
|
||||
continue;
|
||||
}
|
||||
if (modifiers.some(m => /^(?:private|fileprivate)(?:\(set\))?$/.test(m))) {
|
||||
fail(markerOffset, `@Snapshotable field '${fieldName}' cannot be private, fileprivate, private(set), or fileprivate(set)`);
|
||||
continue;
|
||||
}
|
||||
if (modifiers.some(m => m === 'static' || m === 'class')) {
|
||||
fail(markerOffset, `@Snapshotable field '${fieldName}' must be an instance property`);
|
||||
continue;
|
||||
}
|
||||
if (body[at] !== ':') {
|
||||
fail(markerOffset, `@Snapshotable field '${fieldName}' requires an explicit type annotation`);
|
||||
continue;
|
||||
}
|
||||
|
||||
at = skipWhitespace(at + 1);
|
||||
const typeStart = at;
|
||||
let parens = 0;
|
||||
let brackets = 0;
|
||||
let angles = 0;
|
||||
let typeEnd = at;
|
||||
let delimiter = '';
|
||||
for (; at < body.length; at++) {
|
||||
const c = body[at]!;
|
||||
if (c === '(') parens++;
|
||||
else if (c === ')') parens--;
|
||||
else if (c === '[') brackets++;
|
||||
else if (c === ']') brackets--;
|
||||
else if (c === '<') angles++;
|
||||
else if (c === '>') angles = Math.max(0, angles - 1);
|
||||
const topLevel = parens === 0 && brackets === 0 && angles === 0;
|
||||
if (topLevel && (c === '=' || c === '{' || c === ',' || c === ';')) {
|
||||
delimiter = c;
|
||||
break;
|
||||
}
|
||||
if (topLevel && (c === '\n' || c === '\r')) {
|
||||
const soFar = body.slice(typeStart, at).trim();
|
||||
if (soFar.length > 0 && !/(?:->|[&.,])\s*$/.test(soFar)) break;
|
||||
}
|
||||
typeEnd = at + 1;
|
||||
}
|
||||
const typeText = body.slice(typeStart, typeEnd).replace(/\s+/g, ' ').trim();
|
||||
if (typeText.length === 0) {
|
||||
fail(markerOffset, `@Snapshotable field '${fieldName}' requires an explicit type annotation`);
|
||||
continue;
|
||||
}
|
||||
if (delimiter === '{') {
|
||||
fail(markerOffset, `@Snapshotable field '${fieldName}' must be stored and writable`);
|
||||
continue;
|
||||
}
|
||||
if (delimiter === ',') {
|
||||
fail(markerOffset, '@Snapshotable declarations must contain exactly one binding');
|
||||
continue;
|
||||
}
|
||||
if (delimiter === '=') {
|
||||
// A declaration such as `var a: Int = 1, b: Int = 2` reaches `=`
|
||||
// before its binding comma. Scan the initializer at syntax depth zero
|
||||
// so commas in arrays/calls/closures remain valid.
|
||||
let initializerAt = at + 1;
|
||||
let expressionParens = 0;
|
||||
let expressionBrackets = 0;
|
||||
let expressionBraces = 0;
|
||||
let hasSecondBinding = false;
|
||||
for (; initializerAt < body.length; initializerAt++) {
|
||||
const c = body[initializerAt]!;
|
||||
if (c === '(') expressionParens++;
|
||||
else if (c === ')') expressionParens--;
|
||||
else if (c === '[') expressionBrackets++;
|
||||
else if (c === ']') expressionBrackets--;
|
||||
else if (c === '{') expressionBraces++;
|
||||
else if (c === '}') {
|
||||
if (expressionBraces === 0) break;
|
||||
expressionBraces--;
|
||||
}
|
||||
const topLevel = expressionParens === 0 && expressionBrackets === 0 && expressionBraces === 0;
|
||||
if (topLevel && c === ',') {
|
||||
hasSecondBinding = true;
|
||||
break;
|
||||
}
|
||||
if (topLevel && (c === '\n' || c === '\r' || c === ';')) break;
|
||||
}
|
||||
if (hasSecondBinding) {
|
||||
fail(markerOffset, '@Snapshotable declarations must contain exactly one binding');
|
||||
continue;
|
||||
}
|
||||
}
|
||||
const wrappedOptional = optionalWrappedType(typeText);
|
||||
if (wrappedOptional !== undefined && optionalWrappedType(wrappedOptional) !== undefined) {
|
||||
fail(markerOffset, `@Snapshotable field '${fieldName}' cannot use a nested Optional type`);
|
||||
continue;
|
||||
}
|
||||
const typeIssue = snapshotTypeIssue(typeText);
|
||||
if (typeIssue !== undefined) {
|
||||
fail(markerOffset, `@Snapshotable field '${fieldName}' ${typeIssue}`);
|
||||
continue;
|
||||
}
|
||||
|
||||
fields.push({ name: fieldName, typeText });
|
||||
}
|
||||
return { fields, diagnostics };
|
||||
}
|
||||
|
||||
export function computeCacheKey(inputs: {
|
||||
@@ -154,35 +471,263 @@ export function computeCacheKey(inputs: {
|
||||
swiftVersion: string;
|
||||
toolGitRev: string;
|
||||
platformTriple: string;
|
||||
buildId?: string;
|
||||
}): string {
|
||||
const h = createHash('sha256');
|
||||
h.update(`swift=${inputs.swiftVersion}|tool=${inputs.toolGitRev}|platform=${inputs.platformTriple}|`);
|
||||
h.update(`${GENERATOR_FORMAT_VERSION}|swift=${inputs.swiftVersion}|tool=${inputs.toolGitRev}|platform=${inputs.platformTriple}|build=${inputs.buildId ?? 'unknown'}|`);
|
||||
for (const f of inputs.swiftFiles) {
|
||||
const content = readFileSync(f);
|
||||
h.update(`${f}:${content.length}:`);
|
||||
// Cache identity is content-based. Absolute checkout paths must not make
|
||||
// equivalent source trees produce different generated output.
|
||||
h.update(`${content.length}:`);
|
||||
h.update(content);
|
||||
h.update('|');
|
||||
}
|
||||
return h.digest('hex');
|
||||
}
|
||||
|
||||
export function render(specs: AccessorSpec[], buildId: string, accessorHash: string): string {
|
||||
let out = '// AUTO-GENERATED — DO NOT EDIT. Regenerate with /ios-sync.\n';
|
||||
out += '#if DEBUG\nimport Foundation\nimport DebugBridge\n\n';
|
||||
/** Stable snapshot-schema fingerprint, deliberately independent of cache ABI,
|
||||
* source paths, app build provenance, and unmarked source. Field/class order is
|
||||
* source order because restore payload compatibility is an ordered contract. */
|
||||
export function computeAccessorHash(specs: AccessorSpec[]): string {
|
||||
let signature = 'snapshot-schema-v1\n';
|
||||
for (const spec of specs) {
|
||||
out += `@MainActor\npublic enum ${spec.className}Accessor {\n`;
|
||||
out += ` public static func register(_ state: ${spec.className}) {\n`;
|
||||
signature += `C${Buffer.byteLength(spec.className)}:${spec.className}\n`;
|
||||
for (const field of spec.fields) {
|
||||
signature += `F${Buffer.byteLength(field.name)}:${field.name}`;
|
||||
signature += `T${Buffer.byteLength(field.typeText)}:${field.typeText}\n`;
|
||||
}
|
||||
signature += 'E\n';
|
||||
}
|
||||
return createHash('sha256').update(signature).digest('hex');
|
||||
}
|
||||
|
||||
/** Return the wrapped type for one top-level Optional spelling. */
|
||||
export function optionalWrappedType(typeText: string): string | undefined {
|
||||
const type = typeText.trim();
|
||||
if (type.endsWith('?')) {
|
||||
const wrapped = type.slice(0, -1).trim();
|
||||
return wrapped.length > 0 ? wrapped : undefined;
|
||||
}
|
||||
|
||||
const optional = /^(?:Swift\.)?Optional\s*</.exec(type);
|
||||
if (!optional) return undefined;
|
||||
const open = type.indexOf('<', optional.index);
|
||||
let depth = 0;
|
||||
for (let i = open; i < type.length; i++) {
|
||||
if (type[i] === '<') depth++;
|
||||
else if (type[i] === '>') {
|
||||
depth--;
|
||||
if (depth === 0) {
|
||||
if (type.slice(i + 1).trim().length > 0) return undefined;
|
||||
const wrapped = type.slice(open + 1, i).trim();
|
||||
return wrapped.length > 0 ? wrapped : undefined;
|
||||
}
|
||||
}
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function splitTopLevel(type: string, delimiter: string): string[] {
|
||||
const parts: string[] = [];
|
||||
let start = 0;
|
||||
let angle = 0;
|
||||
let square = 0;
|
||||
let paren = 0;
|
||||
for (let i = 0; i < type.length; i++) {
|
||||
const char = type[i]!;
|
||||
if (char === '<') angle++;
|
||||
else if (char === '>') angle--;
|
||||
else if (char === '[') square++;
|
||||
else if (char === ']') square--;
|
||||
else if (char === '(') paren++;
|
||||
else if (char === ')') paren--;
|
||||
else if (char === delimiter && angle === 0 && square === 0 && paren === 0) {
|
||||
parts.push(type.slice(start, i));
|
||||
start = i + 1;
|
||||
}
|
||||
}
|
||||
parts.push(type.slice(start));
|
||||
return parts;
|
||||
}
|
||||
|
||||
function genericArgument(type: string, name: string): string | undefined {
|
||||
const prefix = `${name}<`;
|
||||
if (!type.startsWith(prefix) || !type.endsWith('>')) return undefined;
|
||||
let depth = 0;
|
||||
for (let i = name.length; i < type.length; i++) {
|
||||
if (type[i] === '<') depth++;
|
||||
else if (type[i] === '>') {
|
||||
depth--;
|
||||
if (depth === 0 && i !== type.length - 1) return undefined;
|
||||
if (depth < 0) return undefined;
|
||||
}
|
||||
}
|
||||
return depth === 0 ? type.slice(prefix.length, -1) : undefined;
|
||||
}
|
||||
|
||||
/** Return a user-facing suffix when a Swift type cannot round-trip through
|
||||
* Foundation JSON without custom encoding. The accepted grammar is deliberately
|
||||
* narrow: JSON scalar values, arrays, string-keyed dictionaries, and Optional
|
||||
* compositions of those types. */
|
||||
export function snapshotTypeIssue(typeText: string): string | undefined {
|
||||
const type = typeText.replace(/\s+/g, '');
|
||||
if (type.length === 0) return 'requires a JSON-compatible type';
|
||||
if (type.endsWith('!')) {
|
||||
return 'cannot use an implicitly unwrapped Optional; use T? instead';
|
||||
}
|
||||
|
||||
if (type.endsWith('?')) {
|
||||
const wrapped = type.slice(0, -1);
|
||||
if (wrapped.endsWith('?')
|
||||
|| genericArgument(wrapped, 'Optional') !== undefined
|
||||
|| genericArgument(wrapped, 'Swift.Optional') !== undefined) {
|
||||
return 'cannot use a nested Optional type';
|
||||
}
|
||||
return snapshotTypeIssue(wrapped);
|
||||
}
|
||||
const optional = genericArgument(type, 'Optional') ?? genericArgument(type, 'Swift.Optional');
|
||||
if (optional !== undefined) {
|
||||
if (optional.endsWith('?')
|
||||
|| genericArgument(optional, 'Optional') !== undefined
|
||||
|| genericArgument(optional, 'Swift.Optional') !== undefined) {
|
||||
return 'cannot use a nested Optional type';
|
||||
}
|
||||
return snapshotTypeIssue(optional);
|
||||
}
|
||||
|
||||
const scalar = type === 'CoreGraphics.CGFloat'
|
||||
? 'CGFloat'
|
||||
: (type.startsWith('Swift.') ? type.slice('Swift.'.length) : type);
|
||||
if (JSON_SCALAR_TYPES.has(scalar)) return undefined;
|
||||
|
||||
if (type.startsWith('[') && type.endsWith(']')) {
|
||||
const inner = type.slice(1, -1);
|
||||
const dictionaryParts = splitTopLevel(inner, ':');
|
||||
if (dictionaryParts.length === 1) return snapshotTypeIssue(inner);
|
||||
if (dictionaryParts.length === 2) {
|
||||
const key = dictionaryParts[0]!.replace(/^Swift\./, '');
|
||||
if (key !== 'String') return 'must use String keys for snapshot dictionaries';
|
||||
return snapshotTypeIssue(dictionaryParts[1]!);
|
||||
}
|
||||
return 'requires a JSON-compatible array or dictionary type';
|
||||
}
|
||||
|
||||
const array = genericArgument(type, 'Array') ?? genericArgument(type, 'Swift.Array');
|
||||
if (array !== undefined) return snapshotTypeIssue(array);
|
||||
const dictionary = genericArgument(type, 'Dictionary') ?? genericArgument(type, 'Swift.Dictionary');
|
||||
if (dictionary !== undefined) {
|
||||
const parts = splitTopLevel(dictionary, ',');
|
||||
if (parts.length !== 2) return 'requires a JSON-compatible dictionary type';
|
||||
const key = parts[0]!.replace(/^Swift\./, '');
|
||||
if (key !== 'String') return 'must use String keys for snapshot dictionaries';
|
||||
return snapshotTypeIssue(parts[1]!);
|
||||
}
|
||||
|
||||
return `uses unsupported snapshot type '${typeText}'; use JSON scalar, array, or String-keyed dictionary types`;
|
||||
}
|
||||
|
||||
export function validateAccessorSpecs(specs: AccessorSpec[]): void {
|
||||
const owners = new Map<string, string>();
|
||||
const diagnostics: string[] = [];
|
||||
for (const spec of specs) {
|
||||
for (const field of spec.fields) {
|
||||
const previous = owners.get(field.name);
|
||||
if (previous !== undefined) {
|
||||
diagnostics.push(`snapshot key '${field.name}' is declared by both ${previous} and ${spec.className}; keys must be unique across @Observable types`);
|
||||
} else {
|
||||
owners.set(field.name, spec.className);
|
||||
}
|
||||
}
|
||||
}
|
||||
if (diagnostics.length > 0) throw new AccessorGenerationError(diagnostics);
|
||||
}
|
||||
|
||||
function swiftStringLiteral(value: string): string {
|
||||
return JSON.stringify(value);
|
||||
}
|
||||
|
||||
export function render(specs: AccessorSpec[], buildId: string, accessorHash: string): string {
|
||||
validateAccessorSpecs(specs);
|
||||
let out = '// AUTO-GENERATED — DO NOT EDIT. Regenerate with /ios-sync.\n';
|
||||
out += '#if DEBUG\nimport Foundation\nimport DebugBridgeCore\n\n';
|
||||
for (const spec of specs) {
|
||||
// Accessors compile in the app target beside its usually-internal state
|
||||
// types. Making this API public would make valid internal models fail
|
||||
// Swift type checking (a public signature cannot expose an internal type).
|
||||
out += `@MainActor\nenum ${spec.className}Accessor {\n`;
|
||||
out += ` private static func decodeSnapshotValue<T: Decodable>(_ value: Any, as type: T.Type) -> T? {\n`;
|
||||
out += ` guard JSONSerialization.isValidJSONObject(["value": value]),\n`;
|
||||
out += ` let data = try? JSONSerialization.data(withJSONObject: ["value": value]),\n`;
|
||||
out += ` let decoded = try? JSONDecoder().decode([String: T].self, from: data) else { return nil }\n`;
|
||||
out += ` return decoded["value"]\n`;
|
||||
out += ` }\n\n`;
|
||||
out += ` static func register(_ state: ${spec.className}) {\n`;
|
||||
out += ` StateServer.shared.register(\n`;
|
||||
out += ` buildId: "${buildId}",\n`;
|
||||
out += ` accessorHash: "${accessorHash}",\n`;
|
||||
out += ` atomicRestore: { _ in .ok }\n`;
|
||||
out += ` buildId: {\n`;
|
||||
out += ` let shortVersion = Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String\n`;
|
||||
out += ` let bundleVersion = Bundle.main.object(forInfoDictionaryKey: "CFBundleVersion") as? String\n`;
|
||||
out += ` if let shortVersion, let bundleVersion { return "\\(shortVersion) (\\(bundleVersion))" }\n`;
|
||||
out += ` return shortVersion ?? bundleVersion ?? ${swiftStringLiteral(buildId)}\n`;
|
||||
out += ` }(),\n`;
|
||||
out += ` accessorHash: ${swiftStringLiteral(accessorHash)},\n`;
|
||||
out += ` atomicRestore: { keys, apply in\n`;
|
||||
out += ` // Validate every key and value before assignment.\n`;
|
||||
out += ` // Successful assignments are sequential on MainActor.\n`;
|
||||
spec.fields.forEach((field, index) => {
|
||||
out += ` guard let raw${index} = keys["${field.name}"] else {\n`;
|
||||
out += ` return .missingKey("${field.name}")\n`;
|
||||
out += ` }\n`;
|
||||
const wrapped = optionalWrappedType(field.typeText);
|
||||
if (wrapped !== undefined) {
|
||||
out += ` let restored${index}: ${field.typeText}\n`;
|
||||
out += ` if raw${index} is NSNull {\n`;
|
||||
out += ` restored${index} = nil\n`;
|
||||
out += ` } else if let typed = Self.decodeSnapshotValue(raw${index}, as: ${wrapped}.self) {\n`;
|
||||
out += ` restored${index} = typed\n`;
|
||||
out += ` } else {\n`;
|
||||
out += ` return .typeMismatch("${field.name}")\n`;
|
||||
out += ` }\n`;
|
||||
} else {
|
||||
out += ` guard let restored${index} = Self.decodeSnapshotValue(raw${index}, as: ${field.typeText}.self) else {\n`;
|
||||
out += ` return .typeMismatch("${field.name}")\n`;
|
||||
out += ` }\n`;
|
||||
}
|
||||
});
|
||||
out += ` if apply {\n`;
|
||||
spec.fields.forEach((field, index) => {
|
||||
out += ` state.${field.name} = restored${index}\n`;
|
||||
});
|
||||
out += ` }\n`;
|
||||
out += ` return .ok\n`;
|
||||
out += ` }\n`;
|
||||
out += ` )\n`;
|
||||
for (const field of spec.fields) {
|
||||
const wrapped = optionalWrappedType(field.typeText);
|
||||
out += ` StateServer.shared.registerAccessor(\n`;
|
||||
out += ` key: "${field.name}",\n`;
|
||||
out += ` type: "${field.typeText}",\n`;
|
||||
out += ` read: { state.${field.name} as Any? },\n`;
|
||||
out += ` write: { _ in false }\n`;
|
||||
if (wrapped !== undefined) {
|
||||
out += ` read: {\n`;
|
||||
out += ` guard let value = state.${field.name} else { return NSNull() }\n`;
|
||||
out += ` return value as Any\n`;
|
||||
out += ` },\n`;
|
||||
} else {
|
||||
out += ` read: { state.${field.name} as Any? },\n`;
|
||||
}
|
||||
out += ` write: { value in\n`;
|
||||
if (wrapped !== undefined) {
|
||||
out += ` if value is NSNull {\n`;
|
||||
out += ` state.${field.name} = nil\n`;
|
||||
out += ` return true\n`;
|
||||
out += ` }\n`;
|
||||
out += ` guard let typed = Self.decodeSnapshotValue(value, as: ${wrapped}.self) else { return false }\n`;
|
||||
} else {
|
||||
out += ` guard let typed = Self.decodeSnapshotValue(value, as: ${field.typeText}.self) else { return false }\n`;
|
||||
}
|
||||
out += ` state.${field.name} = typed\n`;
|
||||
out += ` return true\n`;
|
||||
out += ` }\n`;
|
||||
out += ` )\n`;
|
||||
}
|
||||
out += ` }\n}\n\n`;
|
||||
@@ -215,6 +760,15 @@ function detectToolGitRev(): string {
|
||||
}
|
||||
}
|
||||
|
||||
function detectBuildId(): string {
|
||||
if (process.env.APP_BUILD_ID) return process.env.APP_BUILD_ID;
|
||||
const marketing = process.env.MARKETING_VERSION;
|
||||
const build = process.env.CURRENT_PROJECT_VERSION;
|
||||
if (marketing && build) return `${marketing} (${build})`;
|
||||
if (build) return build;
|
||||
return 'unknown';
|
||||
}
|
||||
|
||||
export function defaultCacheRoot(): string {
|
||||
return process.env.GSTACK_IOS_CACHE_ROOT ?? join(homedir(), '.gstack', 'cache', 'gen-accessors');
|
||||
}
|
||||
@@ -223,13 +777,25 @@ export function generate(inputs: GenInputs): GenResult {
|
||||
const inputDir = resolve(inputs.inputDir);
|
||||
const outputDir = resolve(inputs.outputDir ?? inputDir);
|
||||
const cacheRoot = inputs.cacheRoot ?? defaultCacheRoot();
|
||||
const swiftFiles = collectSwiftFiles(inputDir);
|
||||
const swiftFiles = collectSwiftFiles(inputDir, { outputDir });
|
||||
const buildId = inputs.buildId ?? detectBuildId();
|
||||
|
||||
// Parse before cache lookup. This keeps diagnostics deterministic even when
|
||||
// an older cache entry exists, and gives us the schema-only accessor hash.
|
||||
const allSpecs: AccessorSpec[] = [];
|
||||
for (const f of swiftFiles) {
|
||||
const src = readFileSync(f, 'utf-8');
|
||||
allSpecs.push(...parseSwift(src));
|
||||
}
|
||||
validateAccessorSpecs(allSpecs);
|
||||
const accessorHash = computeAccessorHash(allSpecs);
|
||||
|
||||
const cacheKey = computeCacheKey({
|
||||
swiftFiles,
|
||||
swiftVersion: inputs.swiftVersion ?? detectSwiftVersion(),
|
||||
toolGitRev: inputs.toolGitRev ?? detectToolGitRev(),
|
||||
platformTriple: inputs.platformTriple ?? FALLBACK_PLATFORM,
|
||||
buildId,
|
||||
});
|
||||
|
||||
const cachedOutput = join(cacheRoot, cacheKey, 'StateAccessor.swift');
|
||||
@@ -242,18 +808,13 @@ export function generate(inputs: GenInputs): GenResult {
|
||||
return {
|
||||
outputPath: finalOutput,
|
||||
cacheKey,
|
||||
specs: [], // intentionally empty on cache hit (no need to re-parse)
|
||||
accessorHash,
|
||||
specs: allSpecs,
|
||||
cacheHit: true,
|
||||
};
|
||||
}
|
||||
|
||||
// Parse + render fresh
|
||||
const allSpecs: AccessorSpec[] = [];
|
||||
for (const f of swiftFiles) {
|
||||
const src = readFileSync(f, 'utf-8');
|
||||
allSpecs.push(...parseSwift(src));
|
||||
}
|
||||
const rendered = render(allSpecs, inputs.buildId ?? 'unknown', cacheKey);
|
||||
const rendered = render(allSpecs, buildId, accessorHash);
|
||||
writeFileSync(finalOutput, rendered);
|
||||
|
||||
// Populate cache (best-effort — cache failures don't break codegen).
|
||||
@@ -267,6 +828,7 @@ export function generate(inputs: GenInputs): GenResult {
|
||||
return {
|
||||
outputPath: finalOutput,
|
||||
cacheKey,
|
||||
accessorHash,
|
||||
specs: allSpecs,
|
||||
cacheHit: false,
|
||||
};
|
||||
@@ -300,10 +862,18 @@ if (import.meta.main) {
|
||||
const inputDir = args[inputIdx + 1]!;
|
||||
const outputIdx = args.indexOf('--output');
|
||||
const outputDir = outputIdx !== -1 ? args[outputIdx + 1] : undefined;
|
||||
const result = generate({ inputDir, outputDir });
|
||||
process.stdout.write(
|
||||
result.cacheHit
|
||||
? `gen-accessors: cache hit (${result.cacheKey.slice(0, 12)})\n`
|
||||
: `gen-accessors: wrote ${result.specs.length} accessor(s) to ${result.outputPath}\n`,
|
||||
);
|
||||
try {
|
||||
const result = generate({ inputDir, outputDir });
|
||||
process.stdout.write(
|
||||
result.cacheHit
|
||||
? `gen-accessors: cache hit (${result.cacheKey.slice(0, 12)})\n`
|
||||
: `gen-accessors: wrote ${result.specs.length} accessor(s) to ${result.outputPath}\n`,
|
||||
);
|
||||
} catch (error) {
|
||||
if (error instanceof AccessorGenerationError) {
|
||||
process.stderr.write(`${error.message}\n`);
|
||||
process.exit(4);
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -27,12 +27,35 @@ public enum DebugBridgeUIWiring {
|
||||
/// times reinstalls the same closures. Must be called on @MainActor
|
||||
/// because every UIKit access requires the main actor.
|
||||
public static func installAll() {
|
||||
// KIF turns on accessibility automation before walking SwiftUI's AX
|
||||
// tree. Without it SwiftUI exposes only the hosting shell and taps
|
||||
// can report success without invoking Button.action.
|
||||
DebugBridgeTouch.prepareForAutomation()
|
||||
ScreenshotBridge.resolver = { ScreenshotBridgeImpl.capturePNG() }
|
||||
ElementsBridge.resolver = { ElementsBridgeImpl.snapshot() }
|
||||
MutationBridge.resolver = { op, payload in MutationBridgeImpl.dispatch(op: op, payload: payload) }
|
||||
}
|
||||
}
|
||||
|
||||
/// Return the children UIKit exposes specifically to accessibility automation.
|
||||
/// iOS 17 added `automationElements`; unlike the older container APIs it
|
||||
/// preserves identified SwiftUI descendants inside accessibility groups.
|
||||
@MainActor
|
||||
private func debugBridgeAccessibilityChildren(of element: NSObject) -> [NSObject] {
|
||||
if #available(iOS 17.0, *),
|
||||
let automation = element.automationElements,
|
||||
!automation.isEmpty {
|
||||
return automation.compactMap { $0 as? NSObject }
|
||||
}
|
||||
if let accessibility = element.accessibilityElements,
|
||||
!accessibility.isEmpty {
|
||||
return accessibility.compactMap { $0 as? NSObject }
|
||||
}
|
||||
let count = element.accessibilityElementCount()
|
||||
guard count > 0, count < 512 else { return [] }
|
||||
return (0..<count).compactMap { element.accessibilityElement(at: $0) as? NSObject }
|
||||
}
|
||||
|
||||
// MARK: - ScreenshotBridge implementation
|
||||
|
||||
@MainActor
|
||||
@@ -43,7 +66,11 @@ enum ScreenshotBridgeImpl {
|
||||
static func capturePNG() -> Data? {
|
||||
guard let scene = activeScene(), let window = activeKeyWindow(in: scene) else { return nil }
|
||||
let bounds = window.bounds
|
||||
let renderer = UIGraphicsImageRenderer(bounds: bounds)
|
||||
let format = UIGraphicsImageRendererFormat.default()
|
||||
// /tap consumes UIKit window points. Render at 1x so screenshot pixels
|
||||
// use that same coordinate space on 2x/3x devices.
|
||||
format.scale = 1
|
||||
let renderer = UIGraphicsImageRenderer(bounds: bounds, format: format)
|
||||
let image = renderer.image { _ in
|
||||
// drawHierarchy is the documented way to snapshot real UIKit
|
||||
// layers including layer-backed views. afterScreenUpdates: false
|
||||
@@ -61,7 +88,10 @@ enum ScreenshotBridgeImpl {
|
||||
}
|
||||
|
||||
private static func activeKeyWindow(in scene: UIWindowScene) -> UIWindow? {
|
||||
scene.windows.first(where: { $0.isKeyWindow }) ?? scene.windows.first
|
||||
let windows = scene.windows.filter { window in
|
||||
!window.isHidden && !String(describing: type(of: window)).contains("PassThroughWindow")
|
||||
}
|
||||
return windows.first(where: { $0.isKeyWindow }) ?? windows.max(by: { $0.windowLevel < $1.windowLevel })
|
||||
}
|
||||
}
|
||||
|
||||
@@ -76,21 +106,40 @@ enum ElementsBridgeImpl {
|
||||
static func snapshot() -> [JSONDict] {
|
||||
guard let scene = activeScene(), let window = activeKeyWindow(in: scene) else { return [] }
|
||||
var elements: [JSONDict] = []
|
||||
collect(view: window, parentPath: "", windowBounds: window.bounds, into: &elements)
|
||||
var visited = Set<ObjectIdentifier>()
|
||||
var remaining = 2_048
|
||||
collect(
|
||||
view: window,
|
||||
parentPath: "",
|
||||
window: window,
|
||||
visited: &visited,
|
||||
remaining: &remaining,
|
||||
into: &elements
|
||||
)
|
||||
return elements
|
||||
}
|
||||
|
||||
private static func collect(view: UIView, parentPath: String, windowBounds: CGRect, into elements: inout [JSONDict]) {
|
||||
private static func collect(
|
||||
view: UIView,
|
||||
parentPath: String,
|
||||
window: UIWindow,
|
||||
visited: inout Set<ObjectIdentifier>,
|
||||
remaining: inout Int,
|
||||
into elements: inout [JSONDict]
|
||||
) {
|
||||
guard remaining > 0, visited.insert(ObjectIdentifier(view)).inserted else { return }
|
||||
remaining -= 1
|
||||
|
||||
// Skip hidden / zero-size / off-screen subtrees early.
|
||||
if view.isHidden || view.alpha < 0.01 { return }
|
||||
|
||||
let frameInWindow = view.convert(view.bounds, to: nil)
|
||||
if !windowBounds.intersects(frameInWindow) { return }
|
||||
let frameInWindow = view.convert(view.bounds, to: window)
|
||||
if !window.bounds.intersects(frameInWindow) { return }
|
||||
|
||||
let isAccessible = view.isAccessibilityElement
|
||||
let label = view.accessibilityLabel ?? ""
|
||||
let identifier = view.accessibilityIdentifier ?? ""
|
||||
let traits = Int(view.accessibilityTraits.rawValue)
|
||||
let traits = NSNumber(value: view.accessibilityTraits.rawValue)
|
||||
let value = (view.accessibilityValue ?? "") as String
|
||||
let className = String(describing: type(of: view))
|
||||
let path = parentPath.isEmpty ? className : "\(parentPath) > \(className)"
|
||||
@@ -120,66 +169,98 @@ enum ElementsBridgeImpl {
|
||||
])
|
||||
}
|
||||
|
||||
// Recurse into accessibility-elements first (some custom views vend
|
||||
// synthetic children), then UIView subviews. SwiftUI's host views
|
||||
// populate accessibilityElements lazily — many return nil before
|
||||
// VoiceOver triggers them. Force population by reading accessibilityElementCount.
|
||||
_ = view.accessibilityElementCount()
|
||||
if let axElements = view.accessibilityElements {
|
||||
for case let element as NSObject in axElements {
|
||||
if let v = element as? UIView {
|
||||
collect(view: v, parentPath: path, windowBounds: windowBounds, into: &elements)
|
||||
} else {
|
||||
// Synthetic accessibility element (no UIView). Capture frame in screen coords.
|
||||
let af = (element.value(forKey: "accessibilityFrame") as? CGRect) ?? .zero
|
||||
elements.append([
|
||||
"path": "\(path) > <synthetic>",
|
||||
"class": "AccessibilityElement",
|
||||
"label": (element.value(forKey: "accessibilityLabel") as? String) ?? "",
|
||||
"identifier": (element.value(forKey: "accessibilityIdentifier") as? String) ?? "",
|
||||
"value": (element.value(forKey: "accessibilityValue") as? String) ?? "",
|
||||
"traits": (element.value(forKey: "accessibilityTraits") as? NSNumber)?.intValue ?? 0,
|
||||
"frame": [
|
||||
"x": Int(af.origin.x),
|
||||
"y": Int(af.origin.y),
|
||||
"w": Int(af.size.width),
|
||||
"h": Int(af.size.height),
|
||||
],
|
||||
"is_user_interaction_enabled": true,
|
||||
])
|
||||
}
|
||||
}
|
||||
} else {
|
||||
// accessibilityElements is nil — iterate by index. SwiftUI uses
|
||||
// this dynamic protocol pattern; many AX elements only respond
|
||||
// to accessibilityElementCount + accessibilityElement(at:).
|
||||
let count = view.accessibilityElementCount()
|
||||
for i in 0..<count {
|
||||
guard let element = view.accessibilityElement(at: i) as? NSObject else { continue }
|
||||
if let v = element as? UIView {
|
||||
collect(view: v, parentPath: path, windowBounds: windowBounds, into: &elements)
|
||||
} else {
|
||||
let af = (element.value(forKey: "accessibilityFrame") as? CGRect) ?? .zero
|
||||
elements.append([
|
||||
"path": "\(path) > <ax\(i)>",
|
||||
"class": String(describing: type(of: element)),
|
||||
"label": (element.value(forKey: "accessibilityLabel") as? String) ?? "",
|
||||
"identifier": (element.value(forKey: "accessibilityIdentifier") as? String) ?? "",
|
||||
"value": (element.value(forKey: "accessibilityValue") as? String) ?? "",
|
||||
"traits": (element.value(forKey: "accessibilityTraits") as? NSNumber)?.intValue ?? 0,
|
||||
"frame": [
|
||||
"x": Int(af.origin.x),
|
||||
"y": Int(af.origin.y),
|
||||
"w": Int(af.size.width),
|
||||
"h": Int(af.size.height),
|
||||
],
|
||||
"is_user_interaction_enabled": true,
|
||||
])
|
||||
}
|
||||
// Walk automation children before raw subviews. On iOS 17+ this
|
||||
// exposes identified SwiftUI controls nested inside GroupBox/List.
|
||||
for (index, element) in debugBridgeAccessibilityChildren(of: view).enumerated() {
|
||||
if let child = element as? UIView {
|
||||
collect(
|
||||
view: child,
|
||||
parentPath: path,
|
||||
window: window,
|
||||
visited: &visited,
|
||||
remaining: &remaining,
|
||||
into: &elements
|
||||
)
|
||||
} else {
|
||||
appendSynthetic(
|
||||
element,
|
||||
path: "\(path) > <ax\(index)>",
|
||||
window: window,
|
||||
visited: &visited,
|
||||
remaining: &remaining,
|
||||
into: &elements
|
||||
)
|
||||
}
|
||||
}
|
||||
for sub in view.subviews {
|
||||
collect(view: sub, parentPath: path, windowBounds: windowBounds, into: &elements)
|
||||
collect(
|
||||
view: sub,
|
||||
parentPath: path,
|
||||
window: window,
|
||||
visited: &visited,
|
||||
remaining: &remaining,
|
||||
into: &elements
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
private static func appendSynthetic(
|
||||
_ element: NSObject,
|
||||
path: String,
|
||||
window: UIWindow,
|
||||
visited: inout Set<ObjectIdentifier>,
|
||||
remaining: inout Int,
|
||||
into elements: inout [JSONDict]
|
||||
) {
|
||||
guard remaining > 0, visited.insert(ObjectIdentifier(element)).inserted else { return }
|
||||
remaining -= 1
|
||||
|
||||
let screenFrame = (element.value(forKey: "accessibilityFrame") as? CGRect) ?? .zero
|
||||
let frame = window.coordinateSpace.convert(screenFrame, from: window.screen.coordinateSpace)
|
||||
let label = (element.value(forKey: "accessibilityLabel") as? String) ?? ""
|
||||
let identifier = (element.value(forKey: "accessibilityIdentifier") as? String) ?? ""
|
||||
let value = (element.value(forKey: "accessibilityValue") as? String) ?? ""
|
||||
let traits = (element.value(forKey: "accessibilityTraits") as? NSNumber)?.uint64Value ?? 0
|
||||
if !label.isEmpty || !identifier.isEmpty || !value.isEmpty || traits != 0 {
|
||||
elements.append([
|
||||
"path": path,
|
||||
"class": String(describing: type(of: element)),
|
||||
"label": label,
|
||||
"identifier": identifier,
|
||||
"value": value,
|
||||
"traits": NSNumber(value: traits),
|
||||
"frame": [
|
||||
"x": Int(frame.origin.x),
|
||||
"y": Int(frame.origin.y),
|
||||
"w": Int(frame.size.width),
|
||||
"h": Int(frame.size.height),
|
||||
],
|
||||
"is_user_interaction_enabled": true,
|
||||
])
|
||||
}
|
||||
|
||||
// Synthetic SwiftUI nodes are themselves accessibility containers.
|
||||
// Recurse even when this grouping node has no metadata of its own.
|
||||
for (index, child) in debugBridgeAccessibilityChildren(of: element).enumerated() {
|
||||
if let childView = child as? UIView {
|
||||
collect(
|
||||
view: childView,
|
||||
parentPath: path,
|
||||
window: window,
|
||||
visited: &visited,
|
||||
remaining: &remaining,
|
||||
into: &elements
|
||||
)
|
||||
} else {
|
||||
appendSynthetic(
|
||||
child,
|
||||
path: "\(path) > <ax\(index)>",
|
||||
window: window,
|
||||
visited: &visited,
|
||||
remaining: &remaining,
|
||||
into: &elements
|
||||
)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -191,7 +272,10 @@ enum ElementsBridgeImpl {
|
||||
}
|
||||
|
||||
private static func activeKeyWindow(in scene: UIWindowScene) -> UIWindow? {
|
||||
scene.windows.first(where: { $0.isKeyWindow }) ?? scene.windows.first
|
||||
let windows = scene.windows.filter { window in
|
||||
!window.isHidden && !String(describing: type(of: window)).contains("PassThroughWindow")
|
||||
}
|
||||
return windows.first(where: { $0.isKeyWindow }) ?? windows.max(by: { $0.windowLevel < $1.windowLevel })
|
||||
}
|
||||
}
|
||||
|
||||
@@ -210,21 +294,62 @@ enum MutationBridgeImpl {
|
||||
}
|
||||
}
|
||||
|
||||
/// Tap at (x, y) in window coordinates. Delegates to DebugBridgeTouch
|
||||
/// (KIF-derived in-process touch synthesis). The Obj-C target builds a
|
||||
/// real UITouch + IOHIDEvent + UIEvent and dispatches via
|
||||
/// `UIApplication.sendEvent`, which is what UIKit uses for real touches.
|
||||
/// This works for UIControl, SwiftUI Button (via iOS 18+
|
||||
/// `_UIHitTestContext`), gesture recognizers, and anything else that
|
||||
/// listens to the real event-dispatch path.
|
||||
/// Tap at (x, y) in window coordinates. Prefer accessibility activation,
|
||||
/// which is stable for SwiftUI buttons across OS releases, then fall back
|
||||
/// to KIF-derived UITouch synthesis for gesture-only/custom controls.
|
||||
private static func handleTap(_ payload: JSONDict) -> Bool {
|
||||
guard let x = payload["x"] as? NSNumber,
|
||||
let y = payload["y"] as? NSNumber else { return false }
|
||||
let point = CGPoint(x: x.doubleValue, y: y.doubleValue)
|
||||
guard let scene = activeScene(), let window = activeKeyWindow(in: scene) else { return false }
|
||||
if let element = findActivatableAXElement(at: point, in: window),
|
||||
element.accessibilityActivate() {
|
||||
return true
|
||||
}
|
||||
return DebugBridgeTouch.sendTap(at: point, in: window)
|
||||
}
|
||||
|
||||
private static func findActivatableAXElement(at point: CGPoint, in window: UIWindow) -> NSObject? {
|
||||
let screenPoint = window.screen.coordinateSpace.convert(point, from: window.coordinateSpace)
|
||||
var best: NSObject?
|
||||
var bestArea: CGFloat = .infinity
|
||||
var visited = Set<ObjectIdentifier>()
|
||||
var remaining = 2_048
|
||||
|
||||
func consider(frame: CGRect, traits: UInt64, element: NSObject) {
|
||||
guard frame.contains(screenPoint),
|
||||
(traits & UIAccessibilityTraits.button.rawValue) != 0 else { return }
|
||||
let area = frame.width * frame.height
|
||||
if area > 0 && area < bestArea {
|
||||
best = element
|
||||
bestArea = area
|
||||
}
|
||||
}
|
||||
|
||||
func visit(_ element: NSObject) {
|
||||
guard remaining > 0, visited.insert(ObjectIdentifier(element)).inserted else { return }
|
||||
remaining -= 1
|
||||
|
||||
if let view = element as? UIView {
|
||||
guard !view.isHidden, view.alpha >= 0.01,
|
||||
view.convert(view.bounds, to: window).contains(point) else { return }
|
||||
if view.isAccessibilityElement {
|
||||
consider(frame: view.accessibilityFrame, traits: view.accessibilityTraits.rawValue, element: view)
|
||||
}
|
||||
for child in debugBridgeAccessibilityChildren(of: view) { visit(child) }
|
||||
for child in view.subviews { visit(child) }
|
||||
} else {
|
||||
let frame = (element.value(forKey: "accessibilityFrame") as? CGRect) ?? .zero
|
||||
let traits = (element.value(forKey: "accessibilityTraits") as? NSNumber)?.uint64Value ?? 0
|
||||
consider(frame: frame, traits: traits, element: element)
|
||||
for child in debugBridgeAccessibilityChildren(of: element) { visit(child) }
|
||||
}
|
||||
}
|
||||
|
||||
visit(window)
|
||||
return best
|
||||
}
|
||||
|
||||
/// Set text on the first responder if it's a UITextField or UITextView.
|
||||
private static func handleType(_ payload: JSONDict) -> Bool {
|
||||
guard let text = payload["text"] as? String else { return false }
|
||||
@@ -266,7 +391,10 @@ enum MutationBridgeImpl {
|
||||
var off = scroll.contentOffset
|
||||
off.x = max(0, min(scroll.contentSize.width - scroll.bounds.width, off.x + dx))
|
||||
off.y = max(0, min(scroll.contentSize.height - scroll.bounds.height, off.y + dy))
|
||||
scroll.setContentOffset(off, animated: true)
|
||||
// Automation commands return synchronously; do not report
|
||||
// success while the target is still moving underneath the
|
||||
// next tap coordinate.
|
||||
scroll.setContentOffset(off, animated: false)
|
||||
return true
|
||||
}
|
||||
node = cur.superview
|
||||
@@ -301,7 +429,10 @@ enum MutationBridgeImpl {
|
||||
}
|
||||
|
||||
private static func activeKeyWindow(in scene: UIWindowScene) -> UIWindow? {
|
||||
scene.windows.first(where: { $0.isKeyWindow }) ?? scene.windows.first
|
||||
let windows = scene.windows.filter { window in
|
||||
!window.isHidden && !String(describing: type(of: window)).contains("PassThroughWindow")
|
||||
}
|
||||
return windows.first(where: { $0.isKeyWindow }) ?? windows.max(by: { $0.windowLevel < $1.windowLevel })
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -14,12 +14,16 @@ import Foundation
|
||||
public final class DebugBridgeManager {
|
||||
public static let shared = DebugBridgeManager()
|
||||
|
||||
public func start(appState: AppState) {
|
||||
// 1. Register the canonical AppState struct + accessor wiring.
|
||||
// AppStateAccessor.register(_:) is generated by gen-accessors-tool.
|
||||
AppStateAccessor.register(appState)
|
||||
/// Register app-owned generated accessors, then start the server. The
|
||||
/// registration closure is passed in from the consuming app because the
|
||||
/// DebugBridgeCore package cannot import app-target types. On UIKit apps,
|
||||
/// call DebugBridgeUIWiring.installAll() before this method so a warm
|
||||
/// daemon cannot reach uninitialized resolvers during listener startup.
|
||||
public func start<State>(appState: State, register: (State) -> Void) {
|
||||
register(appState)
|
||||
|
||||
// 2. Boot the StateServer.
|
||||
// Boot only after registration so the first snapshot has a real build
|
||||
// id, schema hash, and key set.
|
||||
StateServer.shared.start()
|
||||
|
||||
// 3. The consuming app installs DebugOverlayWindow separately. See
|
||||
@@ -31,19 +35,4 @@ public final class DebugBridgeManager {
|
||||
}
|
||||
}
|
||||
|
||||
// Placeholder. gen-accessors-tool emits the real `AppStateAccessor` enum next
|
||||
// to the app's canonical state struct. Apps that haven't run codegen get a
|
||||
// stub that registers no accessors (snapshot is empty, restore returns
|
||||
// missing-key for every key).
|
||||
@MainActor
|
||||
public enum AppStateAccessor {
|
||||
public static var register: (Any) -> Void = { _ in }
|
||||
}
|
||||
|
||||
// Apps declare their canonical state struct; codegen reads it and emits
|
||||
// AppStateAccessor.register. The app's struct must be `@Observable` and
|
||||
// must hold all snapshot-eligible state in `@Snapshotable`-marked fields.
|
||||
@MainActor
|
||||
public protocol AppState: AnyObject {}
|
||||
|
||||
#endif // DEBUG
|
||||
|
||||
@@ -23,6 +23,10 @@ NS_ASSUME_NONNULL_BEGIN
|
||||
|
||||
@interface DebugBridgeTouch : NSObject
|
||||
|
||||
/// Enable the in-process accessibility automation tree used by SwiftUI and
|
||||
/// UIKit. Call once while installing the debug bridge, before /elements.
|
||||
+ (void)prepareForAutomation;
|
||||
|
||||
/// Synthesize a single tap (TouchPhaseBegan + TouchPhaseEnded) at the given
|
||||
/// window-coordinate point. Returns YES if the touch was delivered (a hit
|
||||
/// view was found and the event passed through UIApplication.sendEvent).
|
||||
|
||||
@@ -126,6 +126,36 @@ static BOOL DBT_LoadIOKit(void) {
|
||||
return _IOKitLoaded;
|
||||
}
|
||||
|
||||
// KIF enables accessibility automation before it asks UIKit/SwiftUI for the
|
||||
// accessibility tree. Without this switch SwiftUI exposes only its hosting
|
||||
// shell: /elements has no controls and a synthesized tap can return YES while
|
||||
// Button.action never fires. Keep this DEBUG-only with the rest of this file.
|
||||
typedef int (*DBTAXSAutomationEnabledFn)(void);
|
||||
typedef void (*DBTAXSSetAutomationEnabledFn)(int);
|
||||
static DBTAXSAutomationEnabledFn _DBTAXSAutomationEnabled;
|
||||
static DBTAXSSetAutomationEnabledFn _DBTAXSSetAutomationEnabled;
|
||||
static int _DBTInitialAutomationState = -1;
|
||||
|
||||
static void DBT_RestoreAccessibilityAutomation(void) {
|
||||
if (_DBTAXSSetAutomationEnabled && _DBTInitialAutomationState >= 0) {
|
||||
_DBTAXSSetAutomationEnabled(_DBTInitialAutomationState);
|
||||
}
|
||||
}
|
||||
|
||||
static void DBT_EnableAccessibilityAutomation(void) {
|
||||
static dispatch_once_t onceToken;
|
||||
dispatch_once(&onceToken, ^{
|
||||
void *handle = dlopen("/usr/lib/libAccessibility.dylib", RTLD_NOW | RTLD_LOCAL);
|
||||
if (!handle) return;
|
||||
_DBTAXSAutomationEnabled = (DBTAXSAutomationEnabledFn)dlsym(handle, "_AXSAutomationEnabled");
|
||||
_DBTAXSSetAutomationEnabled = (DBTAXSSetAutomationEnabledFn)dlsym(handle, "_AXSSetAutomationEnabled");
|
||||
if (!_DBTAXSAutomationEnabled || !_DBTAXSSetAutomationEnabled) return;
|
||||
_DBTInitialAutomationState = _DBTAXSAutomationEnabled();
|
||||
if (!_DBTInitialAutomationState) _DBTAXSSetAutomationEnabled(1);
|
||||
atexit(DBT_RestoreAccessibilityAutomation);
|
||||
});
|
||||
}
|
||||
|
||||
static IOHIDEventRef DBT_IOHIDEventWithTouch(UITouch *touch) CF_RETURNS_RETAINED;
|
||||
static IOHIDEventRef DBT_IOHIDEventWithTouch(UITouch *touch) {
|
||||
if (!DBT_LoadIOKit()) return NULL;
|
||||
@@ -172,6 +202,7 @@ static IOHIDEventRef DBT_IOHIDEventWithTouch(UITouch *touch) {
|
||||
- (void)setGestureView:(UIView *)view;
|
||||
- (void)_setLocationInWindow:(CGPoint)location resetPrevious:(BOOL)resetPrevious;
|
||||
- (void)_setIsFirstTouchForView:(BOOL)firstTouchForView;
|
||||
- (void)_setIsTapToClick:(BOOL)tapToClick;
|
||||
- (void)_setHidEvent:(IOHIDEventRef)event;
|
||||
@end
|
||||
|
||||
@@ -229,6 +260,10 @@ static id DBT_HitTestView(UIWindow *window, CGPoint point) {
|
||||
|
||||
@implementation DebugBridgeTouch
|
||||
|
||||
+ (void)prepareForAutomation {
|
||||
DBT_EnableAccessibilityAutomation();
|
||||
}
|
||||
|
||||
+ (BOOL)sendTapAtPoint:(CGPoint)point inWindow:(UIWindow *)window {
|
||||
if (!window) return NO;
|
||||
|
||||
@@ -247,10 +282,17 @@ static id DBT_HitTestView(UIWindow *window, CGPoint point) {
|
||||
[touch setPhase:UITouchPhaseBegan];
|
||||
if ([touch respondsToSelector:@selector(_setIsFirstTouchForView:)]) {
|
||||
[touch _setIsFirstTouchForView:YES];
|
||||
} else if ([touch respondsToSelector:@selector(_setIsTapToClick:)]) {
|
||||
[touch _setIsTapToClick:YES];
|
||||
Ivar flagsIvar = class_getInstanceVariable([UITouch class], "_touchFlags");
|
||||
if (flagsIvar) {
|
||||
ptrdiff_t offset = ivar_getOffset(flagsIvar);
|
||||
char *flags = (__bridge void *)touch + offset;
|
||||
*flags |= (char)0x01;
|
||||
}
|
||||
}
|
||||
[touch setTimestamp:[[NSProcessInfo processInfo] systemUptime]];
|
||||
if ([touch respondsToSelector:@selector(setGestureView:)] &&
|
||||
[hit isKindOfClass:[UIView class]]) {
|
||||
if ([touch respondsToSelector:@selector(setGestureView:)]) {
|
||||
[touch setGestureView:(UIView *)hit];
|
||||
}
|
||||
|
||||
|
||||
@@ -6,22 +6,35 @@
|
||||
// the DebugBridge target.
|
||||
|
||||
#if DEBUG
|
||||
import DebugBridge
|
||||
import Foundation
|
||||
import DebugBridgeCore
|
||||
#if canImport(UIKit)
|
||||
import DebugBridgeUI
|
||||
#endif
|
||||
|
||||
@MainActor
|
||||
func startGstackDebugBridge(appState: AppState) {
|
||||
func startGstackDebugBridge<State>(
|
||||
appState: State,
|
||||
register: (State) -> Void
|
||||
) {
|
||||
// Read --recording flag from launch arguments
|
||||
let recording = ProcessInfo.processInfo.arguments.contains("--gstack-recording")
|
||||
|
||||
// Install accessibility + screenshot + mutation bridges before starting
|
||||
// the server so the first authenticated request can use them.
|
||||
ElementsBridge.resolver = { AccessibilityScanner.snapshot() }
|
||||
ScreenshotBridge.resolver = { SnapshotCapture.capturePNG() }
|
||||
MutationBridge.resolver = { op, payload in
|
||||
MutationDispatcher.shared.run(op: op, payload: payload)
|
||||
}
|
||||
// Install the UI resolvers before opening the listener. A warm daemon can
|
||||
// issue its first request as soon as StateServer starts; it must never see
|
||||
// the default empty screenshot/elements/mutation handlers.
|
||||
#if canImport(UIKit)
|
||||
DebugBridgeUIWiring.installAll()
|
||||
#endif
|
||||
|
||||
DebugBridgeManager.shared.start(appState: appState, recording: recording)
|
||||
// Generated typed accessors live in the app target, so pass their register
|
||||
// function into the package instead of asking DebugBridgeCore to import
|
||||
// app-owned types.
|
||||
DebugBridgeManager.shared.start(appState: appState, register: register)
|
||||
|
||||
#if canImport(UIKit)
|
||||
DebugOverlayWindow.shared.install(recording: recording)
|
||||
#endif
|
||||
}
|
||||
#endif
|
||||
|
||||
@@ -33,7 +46,10 @@ func startGstackDebugBridge(appState: AppState) {
|
||||
//
|
||||
// init() {
|
||||
// #if DEBUG
|
||||
// startGstackDebugBridge(appState: appState)
|
||||
// startGstackDebugBridge(
|
||||
// appState: appState,
|
||||
// register: MyAppStateAccessor.register
|
||||
// )
|
||||
// #endif
|
||||
// }
|
||||
//
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
// swift-tools-version:5.9
|
||||
// AUTO-GENERATED from gstack/ios-qa/templates/Package.swift.template
|
||||
//
|
||||
// Drop-in SPM package definition for the DebugBridge stack. Three targets:
|
||||
@@ -18,7 +19,6 @@
|
||||
// CI invariant: `swift build -c release` + `nm -j build/Release/<binary>
|
||||
// | grep -q DebugBridge && exit 1`.
|
||||
|
||||
// swift-tools-version:5.9
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
@@ -58,10 +58,5 @@ let package = Package(
|
||||
.define("DEBUG", .when(configuration: .debug)),
|
||||
]
|
||||
),
|
||||
.testTarget(
|
||||
name: "DebugBridgeCoreTests",
|
||||
dependencies: ["DebugBridgeCore"],
|
||||
path: "Tests/DebugBridgeCoreTests"
|
||||
),
|
||||
]
|
||||
)
|
||||
|
||||
@@ -3,12 +3,12 @@
|
||||
//
|
||||
// This file is a TEMPLATE that gen-accessors-tool fills in. The placeholders
|
||||
// are filled per-class from swift-syntax AST inspection of the app's
|
||||
// @Observable types. Only properties marked with @Snapshotable are emitted.
|
||||
// @Observable types. Only properties preceded by `// @Snapshotable` are emitted.
|
||||
//
|
||||
// {{CLASS_NAME}} — the canonical AppState struct name
|
||||
// {{APP_BUILD_ID}} — bundle short version + git SHA at codegen time
|
||||
// {{ACCESSOR_HASH}} — sha256 of accessor signatures (snapshot schema fingerprint)
|
||||
// {{ACCESSORS}} — generated register/read/write blocks per @Snapshotable field
|
||||
// {{ACCESSORS}} — generated register/read/write blocks per marked field
|
||||
|
||||
#if DEBUG
|
||||
|
||||
@@ -21,13 +21,16 @@ public enum {{CLASS_NAME}}Accessor {
|
||||
StateServer.shared.register(
|
||||
buildId: "{{APP_BUILD_ID}}",
|
||||
accessorHash: "{{ACCESSOR_HASH}}",
|
||||
atomicRestore: { keys in
|
||||
// Validate every key + type FIRST, then apply in one struct
|
||||
// assignment so SwiftUI observers see exactly one change.
|
||||
atomicRestore: { keys, apply in
|
||||
// Validate every key + type before mutating any state. Invalid
|
||||
// input therefore cannot leave a partially restored model.
|
||||
var snapshot = state.snapshotable
|
||||
{{VALIDATION_BLOCK}}
|
||||
// Apply atomically.
|
||||
state.snapshotable = snapshot
|
||||
// StateServer validates every model first, then invokes the
|
||||
// same handlers with apply=true for a cross-model commit.
|
||||
if apply {
|
||||
state.snapshotable = snapshot
|
||||
}
|
||||
return .ok
|
||||
}
|
||||
)
|
||||
|
||||
@@ -59,18 +59,20 @@ public final class StateServer {
|
||||
private var writeHandlers: [String: WriteHandler] = [:]
|
||||
private var typeNames: [String: TypeName] = [:]
|
||||
|
||||
// Atomic-restore hook. Codegen wires this to the canonical AppState struct.
|
||||
// Restore replaces the entire struct in one assignment so SwiftUI's Combine
|
||||
// pipeline observes exactly one change notification — true observable
|
||||
// atomicity. @MainActor alone doesn't guarantee that.
|
||||
public typealias AtomicRestoreFn = (JSONDict) -> RestoreResult
|
||||
// Validated-restore hooks. Every generated model registers one two-phase
|
||||
// handler. The server validates all models before it lets any model mutate,
|
||||
// so invalid input can never cause a cross-model partial restore.
|
||||
// Valid restores apply properties on MainActor; observers may receive one
|
||||
// change notification per property because arbitrary @Observable models do
|
||||
// not expose a general single-assignment transaction API.
|
||||
public typealias AtomicRestoreFn = (JSONDict, Bool) -> RestoreResult
|
||||
public enum RestoreResult {
|
||||
case ok
|
||||
case missingKey(String)
|
||||
case typeMismatch(String)
|
||||
case schemaMismatch(expected: String, got: String)
|
||||
}
|
||||
private var atomicRestore: AtomicRestoreFn?
|
||||
private var atomicRestores: [AtomicRestoreFn] = []
|
||||
|
||||
// Snapshot schema hash — written by codegen, stable across builds with
|
||||
// identical accessor signatures.
|
||||
@@ -109,7 +111,7 @@ public final class StateServer {
|
||||
public func register(buildId: String, accessorHash: String, atomicRestore: @escaping AtomicRestoreFn) {
|
||||
self.appBuildId = buildId
|
||||
self.accessorHash = accessorHash
|
||||
self.atomicRestore = atomicRestore
|
||||
self.atomicRestores.append(atomicRestore)
|
||||
}
|
||||
|
||||
public func registerAccessor(key: String, type: String, read: @escaping ReadHandler, write: @escaping WriteHandler) {
|
||||
@@ -284,6 +286,7 @@ public final class StateServer {
|
||||
"version": "1.0.0",
|
||||
"build": appBuildId,
|
||||
"accessor_hash": accessorHash,
|
||||
"bundle_id": Bundle.main.bundleIdentifier ?? "unknown",
|
||||
])
|
||||
return
|
||||
}
|
||||
@@ -476,22 +479,36 @@ public final class StateServer {
|
||||
send(connection: connection, status: 400, body: ["error": "missing_keys"])
|
||||
return
|
||||
}
|
||||
guard let restore = atomicRestore else {
|
||||
guard !atomicRestores.isEmpty else {
|
||||
send(connection: connection, status: 503, body: ["error": "atomic_restore_not_registered"])
|
||||
return
|
||||
}
|
||||
// Validate-then-apply via the codegen-supplied closure. The closure does
|
||||
// a single struct-assignment so SwiftUI sees one change notification.
|
||||
switch restore(keys) {
|
||||
case .ok:
|
||||
send(connection: connection, status: 200, body: ["ok": true])
|
||||
case .missingKey(let k):
|
||||
send(connection: connection, status: 400, body: ["error": "validation_failed", "key": k, "reason": "missing"])
|
||||
case .typeMismatch(let k):
|
||||
send(connection: connection, status: 400, body: ["error": "validation_failed", "key": k, "reason": "type-mismatch"])
|
||||
case .schemaMismatch(let expected, let got):
|
||||
send(connection: connection, status: 409, body: ["error": "schema_mismatch", "expected_hash": expected, "got_hash": got])
|
||||
// Phase one validates every registered model without assignment.
|
||||
for restore in atomicRestores {
|
||||
switch restore(keys, false) {
|
||||
case .ok:
|
||||
continue
|
||||
case .missingKey(let k):
|
||||
send(connection: connection, status: 400, body: ["error": "validation_failed", "key": k, "reason": "missing"])
|
||||
return
|
||||
case .typeMismatch(let k):
|
||||
send(connection: connection, status: 400, body: ["error": "validation_failed", "key": k, "reason": "type-mismatch"])
|
||||
return
|
||||
case .schemaMismatch(let expected, let got):
|
||||
send(connection: connection, status: 409, body: ["error": "schema_mismatch", "expected_hash": expected, "got_hash": got])
|
||||
return
|
||||
}
|
||||
}
|
||||
|
||||
// Phase two applies only after every model accepted the immutable input.
|
||||
// A valid multi-field restore may notify once per property.
|
||||
for restore in atomicRestores {
|
||||
guard case .ok = restore(keys, true) else {
|
||||
send(connection: connection, status: 500, body: ["error": "restore_apply_failed"])
|
||||
return
|
||||
}
|
||||
}
|
||||
send(connection: connection, status: 200, body: ["ok": true])
|
||||
}
|
||||
|
||||
// MARK: Stubs (real impls live in DebugBridgeManager + UIKit)
|
||||
@@ -522,9 +539,19 @@ public final class StateServer {
|
||||
// MARK: Response
|
||||
|
||||
private func send(connection: NWConnection, status: Int, body: JSONDict) {
|
||||
let json = (try? JSONSerialization.data(withJSONObject: body)) ?? Data("{}".utf8)
|
||||
let responseStatus: Int
|
||||
let json: Data
|
||||
if JSONSerialization.isValidJSONObject(body),
|
||||
let encoded = try? JSONSerialization.data(withJSONObject: body) {
|
||||
responseStatus = status
|
||||
json = encoded
|
||||
} else {
|
||||
logger.error("Refusing to send a non-JSON response body")
|
||||
responseStatus = 500
|
||||
json = Data("{\"error\":\"response_not_json_serializable\"}".utf8)
|
||||
}
|
||||
let statusText: String
|
||||
switch status {
|
||||
switch responseStatus {
|
||||
case 200: statusText = "OK"
|
||||
case 400: statusText = "Bad Request"
|
||||
case 401: statusText = "Unauthorized"
|
||||
@@ -537,7 +564,7 @@ public final class StateServer {
|
||||
case 503: statusText = "Service Unavailable"
|
||||
default: statusText = "Status"
|
||||
}
|
||||
let header = "HTTP/1.1 \(status) \(statusText)\r\nContent-Type: application/json\r\nContent-Length: \(json.count)\r\nConnection: close\r\n\r\n"
|
||||
let header = "HTTP/1.1 \(responseStatus) \(statusText)\r\nContent-Type: application/json\r\nContent-Length: \(json.count)\r\nConnection: close\r\n\r\n"
|
||||
var packet = Data(header.utf8)
|
||||
packet.append(json)
|
||||
connection.send(content: packet, completion: .contentProcessed { _ in
|
||||
|
||||
Reference in New Issue
Block a user