@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 439 lines 18.7 KB
Raw
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 }))