The best way to control Claude Code, Codex and more from any computer or phone
| 1 | /** |
| 2 | * The `graphqlgen --watch` loop. |
| 3 | * |
| 4 | * The loop runs over the event streams `options.watch` returns, so tests can |
| 5 | * inject events and the CLI plugs in `FileSystem.watch`. |
| 6 | * |
| 7 | * @internal |
| 8 | */ |
| 9 | import * as Cause from "effect/Cause" |
| 10 | import * as Console from "effect/Console" |
| 11 | import * as Deferred from "effect/Deferred" |
| 12 | import * as Effect from "effect/Effect" |
| 13 | import * as Fiber from "effect/Fiber" |
| 14 | import * as FileSystem from "effect/FileSystem" |
| 15 | import * as Option from "effect/Option" |
| 16 | import * as Path from "effect/Path" |
| 17 | import * as PlatformError from "effect/PlatformError" |
| 18 | import * as Queue from "effect/Queue" |
| 19 | import * as Result from "effect/Result" |
| 20 | import * as Stream from "effect/Stream" |
| 21 | import * as Cli from "./Cli.ts" |
| 22 | import * as Generate from "./Generate.ts" |
| 23 | import * as Glob from "./Glob.ts" |
| 24 | |
| 25 | /** How long the loop waits after the last relevant event before it regenerates. */ |
| 26 | const debounce = "50 millis" |
| 27 | |
| 28 | /** |
| 29 | * Generates at startup and 50 ms after the last relevant event. Watches the |
| 30 | * config, schema and document glob roots; generated files are ignored. |
| 31 | * Successful cycles write changed files, delete stale outputs and log counts. |
| 32 | * Errors print diagnostics without writing. Unmapped-scalar warnings are |
| 33 | * printed only when their set changes. Invalid config edits keep the previous |
| 34 | * config; only a startup config failure ends the loop. |
| 35 | * |
| 36 | * `configPath` is absolute. `watch(path, kind)` uses `FileSystem.watch` |
| 37 | * semantics: event paths are relative to the watched directory or a watched |
| 38 | * file's parent. Missing roots are watched through their first missing |
| 39 | * directory. Ended or failed watchers are replaced on the next cycle. |
| 40 | * |
| 41 | * Generation waits for every watch to acknowledge installation via `onReady`. |
| 42 | * Events are buffered while installation and generation are in progress. |
| 43 | * Targets are reconciled after each cycle without polling. |
| 44 | */ |
| 45 | export const run: (options: { |
| 46 | readonly configPath: string |
| 47 | /** Call `onReady` only after installation, when the stream can buffer events. */ |
| 48 | readonly watch: ( |
| 49 | path: string, |
| 50 | kind: "file" | "directory", |
| 51 | onReady: () => void |
| 52 | ) => Stream.Stream<FileSystem.WatchEvent, PlatformError.PlatformError> |
| 53 | }) => Effect.Effect<never, Cli.ConfigLoadError, FileSystem.FileSystem | Path.Path> = Effect.fnUntraced( |
| 54 | function*(options) { |
| 55 | const fs = yield* FileSystem.FileSystem |
| 56 | const path = yield* Path.Path |
| 57 | const configPath = path.resolve(options.configPath) |
| 58 | const cwd = path.dirname(configPath) |
| 59 | const cache = Generate.makeCache() |
| 60 | |
| 61 | /** The config file's mtime, used to spot edits and to bust the import cache. */ |
| 62 | const configVersion = fs.stat(configPath).pipe( |
| 63 | Effect.map((info) => Option.getOrElse(Option.map(info.mtime, (date) => date.getTime()), () => 0)), |
| 64 | Effect.orElseSucceed(() => undefined) |
| 65 | ) |
| 66 | |
| 67 | const initialVersion = yield* configVersion |
| 68 | const initialConfig = yield* Cli.loadConfig(configPath, initialVersion) |
| 69 | const state = { |
| 70 | config: initialConfig, |
| 71 | configVersion: initialVersion, |
| 72 | schemaPath: path.resolve(cwd, initialConfig.schema), |
| 73 | globs: initialConfig.documents.map(Glob.make), |
| 74 | /** Files the last successful cycle generated or deleted; events for them are ignored. */ |
| 75 | outputs: new Set<string>(), |
| 76 | /** The first missing directory of each missing glob root; its creation is relevant. */ |
| 77 | pending: new Set<string>(), |
| 78 | /** The formatted warnings the last successful cycle printed or kept quiet about. */ |
| 79 | warnings: new Set<string>() |
| 80 | } |
| 81 | |
| 82 | // ------------------------------------------------------------------------- |
| 83 | // Events |
| 84 | // ------------------------------------------------------------------------- |
| 85 | |
| 86 | const isRelevant = (absolute: string): boolean => { |
| 87 | if (absolute === configPath || absolute === state.schemaPath || state.pending.has(absolute)) return true |
| 88 | if (state.outputs.has(absolute)) return false |
| 89 | const relative = path.relative(cwd, absolute).split(path.sep).join("/") |
| 90 | const segments = relative.split("/") |
| 91 | const inside = segments.slice(segments.findIndex((segment) => segment !== "..")) |
| 92 | // The generator never reads documents under node_modules or dot-directories. |
| 93 | if (inside.some(Glob.isSkipped)) return false |
| 94 | return state.globs.some((glob) => glob.matches(relative)) |
| 95 | } |
| 96 | |
| 97 | const events = yield* Queue.unbounded<string>() |
| 98 | |
| 99 | interface Target { |
| 100 | /** `pending` is the first missing directory on the way to a glob root. */ |
| 101 | readonly kind: "file" | "tree" | "pending" |
| 102 | readonly path: string |
| 103 | /** Event paths are relative to this directory. */ |
| 104 | readonly base: string |
| 105 | } |
| 106 | |
| 107 | const exists = (file: string) => fs.exists(file).pipe(Effect.orElseSucceed(() => false)) |
| 108 | |
| 109 | /** `file` itself when its directory exists, otherwise the first missing directory above it. */ |
| 110 | const firstMissing = Effect.fnUntraced(function*(file: string) { |
| 111 | let missing = file |
| 112 | while (true) { |
| 113 | const parent = path.dirname(missing) |
| 114 | if (parent === missing || (yield* exists(parent))) return missing |
| 115 | missing = parent |
| 116 | } |
| 117 | }) |
| 118 | |
| 119 | /** |
| 120 | * The config file, the schema file and each `documents` glob root. Every |
| 121 | * target's `base` directory exists, so a watch only ends when something |
| 122 | * was deleted. |
| 123 | */ |
| 124 | const targets = Effect.gen(function*() { |
| 125 | const found = new Map<string, Target>() |
| 126 | for (const file of [configPath, state.schemaPath]) { |
| 127 | const watched = yield* firstMissing(file) |
| 128 | found.set(watched, { kind: watched === file ? "file" : "pending", path: watched, base: path.dirname(watched) }) |
| 129 | } |
| 130 | for (const glob of state.globs) { |
| 131 | const directory = path.join(cwd, glob.root) |
| 132 | if (glob.skipped || found.get(directory)?.kind === "tree") continue |
| 133 | if (yield* exists(directory)) { |
| 134 | found.set(directory, { kind: "tree", path: directory, base: directory }) |
| 135 | } else { |
| 136 | const missing = yield* firstMissing(directory) |
| 137 | if (!found.has(missing)) found.set(missing, { kind: "pending", path: missing, base: path.dirname(missing) }) |
| 138 | } |
| 139 | } |
| 140 | return Array.from(found.values()) |
| 141 | }) |
| 142 | |
| 143 | /** Set when a watch stream ended or failed, so the next `subscribe` starts over. */ |
| 144 | let stale = false |
| 145 | |
| 146 | const watchTarget = (target: Target, ready: Deferred.Deferred<void>) => |
| 147 | options.watch(target.path, target.kind === "tree" ? "directory" : "file", () => { |
| 148 | Deferred.doneUnsafe(ready, Effect.void) |
| 149 | }).pipe( |
| 150 | Stream.runForEach((event) => { |
| 151 | const absolute = path.resolve(target.base, event.path) |
| 152 | return isRelevant(absolute) ? Queue.offer(events, absolute) : Effect.void |
| 153 | }), |
| 154 | Effect.matchEffect({ |
| 155 | onFailure: (error) => |
| 156 | Effect.andThen( |
| 157 | Effect.sync(() => (stale = true)), |
| 158 | Console.error(`error: could not watch ${Cli.displayPath(path, target.path)}: ${error.message}`) |
| 159 | ), |
| 160 | onSuccess: () => Effect.andThen(Effect.sync(() => (stale = true)), Queue.offer(events, target.path)) |
| 161 | }), |
| 162 | // A failed or ended stream must not leave subscription waiting forever. |
| 163 | Effect.ensuring(Deferred.succeed(ready, undefined)) |
| 164 | ) |
| 165 | |
| 166 | let watching: { readonly key: string; readonly fiber: Fiber.Fiber<void> } | undefined |
| 167 | const targetKey = (current: ReadonlyArray<Target>) => |
| 168 | current.map((target) => `${target.kind}:${target.path}`).join("\0") |
| 169 | /** Watches the current targets, replacing the previous watchers when they changed or one stopped. */ |
| 170 | const subscribe = Effect.gen(function*() { |
| 171 | const current = yield* targets |
| 172 | const key = targetKey(current) |
| 173 | if (!stale && watching?.key === key) return |
| 174 | if (watching !== undefined) yield* Fiber.interrupt(watching.fiber) |
| 175 | stale = false |
| 176 | state.pending = new Set(current.filter((target) => target.kind === "pending").map((target) => target.path)) |
| 177 | // Call watch on the loop fiber; only consumption of its streams is forked. |
| 178 | const ready = yield* Effect.forEach(current, () => Deferred.make<void>()) |
| 179 | const streams = current.map((target, index) => watchTarget(target, ready[index])) |
| 180 | const fiber = yield* Effect.all(streams, { concurrency: "unbounded", discard: true }).pipe( |
| 181 | Effect.forkChild |
| 182 | ) |
| 183 | watching = { key, fiber } |
| 184 | yield* Effect.forEach(ready, Deferred.await, { concurrency: "unbounded", discard: true }) |
| 185 | }) |
| 186 | |
| 187 | /** Reconcile roots that appeared or disappeared during this cycle, without polling. */ |
| 188 | const reconcile = Effect.gen(function*() { |
| 189 | if (targetKey(yield* targets) !== watching?.key) yield* Queue.offer(events, state.schemaPath) |
| 190 | }) |
| 191 | |
| 192 | // ------------------------------------------------------------------------- |
| 193 | // Cycles |
| 194 | // ------------------------------------------------------------------------- |
| 195 | |
| 196 | const generate = Effect.gen(function*() { |
| 197 | const generated = yield* Effect.result(Generate.generate(state.config, { cwd, cache })) |
| 198 | if (Result.isFailure(generated)) { |
| 199 | return yield* Console.error(`error: ${generated.failure.message}`) |
| 200 | } |
| 201 | const result = generated.success |
| 202 | const warnings = new Set<string>() |
| 203 | let errors = 0 |
| 204 | for (const diagnostic of result.diagnostics) { |
| 205 | const formatted = Cli.formatDiagnostic(path, cwd, diagnostic) |
| 206 | if (diagnostic.severity === "error") { |
| 207 | errors++ |
| 208 | yield* Console.error(formatted) |
| 209 | } else { |
| 210 | warnings.add(formatted) |
| 211 | if (!state.warnings.has(formatted)) yield* Console.error(formatted) |
| 212 | } |
| 213 | } |
| 214 | if (errors > 0) { |
| 215 | return yield* Console.error(Cli.errorSummary(errors)) |
| 216 | } |
| 217 | state.warnings = warnings |
| 218 | const written = yield* Effect.result( |
| 219 | Cli.planChanges(result).pipe(Effect.tap(Cli.writeChanges)) |
| 220 | ) |
| 221 | if (Result.isFailure(written)) { |
| 222 | return yield* Console.error(written.failure.message) |
| 223 | } |
| 224 | const changes = written.success |
| 225 | state.outputs = new Set([...result.files.map((file) => file.path), ...result.deletes]) |
| 226 | const count = changes.creates.length + changes.updates.length |
| 227 | yield* Console.log(`regenerated ${count} ${count === 1 ? "file" : "files"}, deleted ${changes.deletes.length}`) |
| 228 | }) |
| 229 | |
| 230 | /** Installs the watches, then regenerates and reconciles the targets. */ |
| 231 | const refresh = Effect.gen(function*() { |
| 232 | yield* subscribe |
| 233 | yield* generate |
| 234 | yield* reconcile |
| 235 | }) |
| 236 | |
| 237 | /** |
| 238 | * Reloads the config when its mtime changed, then refreshes. A config that |
| 239 | * fails to load is reported and the previous one kept; the cycle still |
| 240 | * regenerates when something besides the config changed. |
| 241 | */ |
| 242 | const cycle = Effect.fnUntraced(function*(changed: ReadonlySet<string>) { |
| 243 | const version = yield* configVersion |
| 244 | if (version !== state.configVersion) { |
| 245 | state.configVersion = version |
| 246 | const loaded = yield* Effect.result(Cli.loadConfig(configPath, version)) |
| 247 | if (Result.isFailure(loaded)) { |
| 248 | yield* Console.error(loaded.failure.message) |
| 249 | if (!Array.from(changed).some((file) => file !== configPath)) return |
| 250 | } else { |
| 251 | state.config = loaded.success |
| 252 | state.schemaPath = path.resolve(cwd, loaded.success.schema) |
| 253 | state.globs = loaded.success.documents.map(Glob.make) |
| 254 | } |
| 255 | } |
| 256 | yield* refresh |
| 257 | }) |
| 258 | |
| 259 | yield* refresh |
| 260 | |
| 261 | const pending = new Set<string>() |
| 262 | yield* Stream.fromQueue(events).pipe( |
| 263 | Stream.tap((file) => Effect.sync(() => pending.add(file))), |
| 264 | Stream.debounce(debounce), |
| 265 | Stream.runForEach(() => |
| 266 | Effect.suspend(() => { |
| 267 | const changed = new Set(pending) |
| 268 | pending.clear() |
| 269 | return cycle(changed) |
| 270 | }) |
| 271 | ) |
| 272 | ) |
| 273 | return yield* Effect.never |
| 274 | } |
| 275 | ) |
| 276 | |
| 277 | // ----------------------------------------------------------------------------- |
| 278 | // FileSystem.watch |
| 279 | // ----------------------------------------------------------------------------- |
| 280 | |
| 281 | /** |
| 282 | * The `watch` option of {@link run} backed by `FileSystem.watch`, for the |
| 283 | * CLI. |
| 284 | * |
| 285 | * A file is watched through its directory, so a file that doesn't exist yet, |
| 286 | * or that an editor saves by renaming a new file over it, is still seen. |
| 287 | * |
| 288 | * A directory is watched one directory at a time rather than with |
| 289 | * `recursive: true`: Node's recursive watcher on Linux keeps following the |
| 290 | * old file after a rename-over save and misses every later edit. New |
| 291 | * subdirectories are picked up as they appear, with a `Create` event for each |
| 292 | * file already in them. `node_modules` and dot-directories are skipped. |
| 293 | * |
| 294 | * The stream ends when the watched directory is deleted, and fails when |
| 295 | * watching fails for any other reason, e.g. when the system runs out of |
| 296 | * inotify watches. |
| 297 | */ |
| 298 | export const fileSystemWatch = (fs: FileSystem.FileSystem, path: Path.Path) => |
| 299 | ( |
| 300 | target: string, |
| 301 | kind: "file" | "directory", |
| 302 | onReady: () => void |
| 303 | ): Stream.Stream<FileSystem.WatchEvent, PlatformError.PlatformError> => |
| 304 | kind === "file" |
| 305 | ? watchDirectory(fs, path.dirname(target), onReady).pipe( |
| 306 | Stream.filter((event) => event.path === path.basename(target)) |
| 307 | ) |
| 308 | : watchTree(fs, path, target, onReady) |
| 309 | |
| 310 | /** |
| 311 | * `FileSystem.watch` on one directory, ending when the directory is deleted. |
| 312 | * Node doesn't end the watch then: it reports a rename of the directory's own |
| 313 | * name and goes quiet. A failure while the directory still exists is passed |
| 314 | * on, including a defect: Node throws `EACCES` and `ENOSPC` synchronously from |
| 315 | * `fs.watch`. |
| 316 | */ |
| 317 | const watchDirectory = ( |
| 318 | fs: FileSystem.FileSystem, |
| 319 | directory: string, |
| 320 | onReady: () => void |
| 321 | ): Stream.Stream<FileSystem.WatchEvent, PlatformError.PlatformError> => { |
| 322 | const gone = fs.exists(directory).pipe( |
| 323 | Effect.map((exists) => !exists), |
| 324 | Effect.orElseSucceed(() => false) |
| 325 | ) |
| 326 | return fs.watch(directory, { onReady }).pipe( |
| 327 | Stream.takeUntilEffect((event) => event._tag === "Remove" ? gone : Effect.succeed(false)), |
| 328 | Stream.catchCause((cause) => { |
| 329 | if (Cause.hasInterruptsOnly(cause)) return Stream.failCause(cause) |
| 330 | const failure = Cause.squash(cause) |
| 331 | const error = PlatformError.isPlatformError(failure) ? failure : PlatformError.systemError({ |
| 332 | _tag: "Unknown", |
| 333 | module: "FileSystem", |
| 334 | method: "watch", |
| 335 | pathOrDescriptor: directory, |
| 336 | description: failure instanceof Error ? failure.message : String(failure), |
| 337 | cause: failure |
| 338 | }) |
| 339 | return Stream.unwrap(Effect.map(gone, (isGone) => isGone ? Stream.empty : Stream.fail(error))) |
| 340 | }) |
| 341 | ) |
| 342 | } |
| 343 | |
| 344 | const watchTree = ( |
| 345 | fs: FileSystem.FileSystem, |
| 346 | path: Path.Path, |
| 347 | root: string, |
| 348 | onReady: () => void |
| 349 | ): Stream.Stream<FileSystem.WatchEvent, PlatformError.PlatformError> => |
| 350 | Stream.callback<FileSystem.WatchEvent, PlatformError.PlatformError>(Effect.fnUntraced(function*(queue) { |
| 351 | const scope = yield* Effect.scope |
| 352 | const watchers = new Map<string, { readonly fiber: Fiber.Fiber<void>; readonly ready: Deferred.Deferred<void> }>() |
| 353 | const offer = (event: FileSystem.WatchEvent) => |
| 354 | Queue.offer(queue, { _tag: event._tag, path: path.relative(root, event.path) }) |
| 355 | |
| 356 | /** Visits the subdirectories and files directly under `directory`. */ |
| 357 | const children = Effect.fnUntraced(function*(directory: string) { |
| 358 | const entries = yield* fs.readDirectory(directory).pipe(Effect.orElseSucceed(() => [])) |
| 359 | const directories: Array<string> = [] |
| 360 | const files: Array<string> = [] |
| 361 | for (const entry of entries) { |
| 362 | const absolute = path.join(directory, entry) |
| 363 | const info = yield* fs.stat(absolute).pipe(Effect.option) |
| 364 | if (Option.isNone(info)) continue |
| 365 | if (info.value.type === "Directory") { |
| 366 | if (!Glob.isSkipped(entry)) directories.push(absolute) |
| 367 | } else { |
| 368 | files.push(absolute) |
| 369 | } |
| 370 | } |
| 371 | return { directories, files } |
| 372 | }) |
| 373 | |
| 374 | /** |
| 375 | * Watches `directory` and everything under it; `announce` reports its |
| 376 | * files as created. Deleting the root ends the stream; a watch that |
| 377 | * fails takes the whole stream down with it. |
| 378 | */ |
| 379 | const add: (directory: string, announce: boolean) => Effect.Effect<void> = (directory, announce) => |
| 380 | Effect.uninterruptibleMask((restore) => |
| 381 | Effect.gen(function*() { |
| 382 | const existing = watchers.get(directory) |
| 383 | if (existing !== undefined) return yield* restore(Deferred.await(existing.ready)) |
| 384 | // Share readiness with concurrent discovery of the same subtree. |
| 385 | const installed = yield* Deferred.make<void>() |
| 386 | const ready = yield* Deferred.make<void>() |
| 387 | const fiber = yield* watchDirectory(fs, directory, () => { |
| 388 | Deferred.doneUnsafe(ready, Effect.void) |
| 389 | }).pipe( |
| 390 | Stream.runForEach((event) => handle(directory, event)), |
| 391 | Effect.matchEffect({ |
| 392 | onFailure: (error) => Queue.fail(queue, error), |
| 393 | onSuccess: () => directory === root ? Queue.end(queue) : Effect.void |
| 394 | }), |
| 395 | Effect.asVoid, |
| 396 | Effect.ensuring(Deferred.succeed(ready, undefined)), |
| 397 | Effect.ensuring(Effect.sync(() => watchers.delete(directory))), |
| 398 | restore, |
| 399 | Effect.forkIn(scope) |
| 400 | ) |
| 401 | watchers.set(directory, { fiber, ready: installed }) |
| 402 | // Publishing shared completion and registering its finalizer must be |
| 403 | // atomic: subtree removal can interrupt this discovery owner. |
| 404 | yield* restore(Effect.gen(function*() { |
| 405 | yield* Deferred.await(ready) |
| 406 | const found = yield* children(directory) |
| 407 | if (announce) { |
| 408 | for (const file of found.files) yield* offer({ _tag: "Create", path: file }) |
| 409 | } |
| 410 | for (const child of found.directories) yield* add(child, announce) |
| 411 | })).pipe(Effect.ensuring(Deferred.succeed(installed, undefined))) |
| 412 | }) |
| 413 | ) |
| 414 | |
| 415 | /** Stops watching `directory` and everything under it. */ |
| 416 | const remove = (directory: string) => |
| 417 | Effect.forEach( |
| 418 | Array.from(watchers).filter(([watched]) => watched === directory || watched.startsWith(directory + path.sep)), |
| 419 | ([, { fiber }]) => Fiber.interrupt(fiber), |
| 420 | { discard: true } |
| 421 | ) |
| 422 | |
| 423 | const handle: (directory: string, event: FileSystem.WatchEvent) => Effect.Effect<void> = Effect.fnUntraced( |
| 424 | function*(directory, event) { |
| 425 | const absolute = path.join(directory, event.path) |
| 426 | yield* offer({ _tag: event._tag, path: absolute }) |
| 427 | if (event._tag === "Remove") return yield* remove(absolute) |
| 428 | if (event._tag !== "Create" || Glob.isSkipped(path.basename(absolute))) return |
| 429 | const info = yield* fs.stat(absolute).pipe(Effect.option) |
| 430 | if (Option.isNone(info) || info.value.type !== "Directory") return |
| 431 | // A directory deleted and created again may still have its old watcher. |
| 432 | yield* remove(absolute) |
| 433 | yield* add(absolute, true) |
| 434 | } |
| 435 | ) |
| 436 | |
| 437 | yield* add(root, false) |
| 438 | onReady() |
| 439 | })) |