@locker/cli 0.28.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,124 @@
1
+ import chokidar from 'chokidar';
2
+
3
+ // Re-run debounce. A single editor save often emits several filesystem
4
+ // events in quick succession (write, then a metadata/atime touch, then a
5
+ // rename on atomic-save editors). Collapsing them into one re-run inside a
6
+ // short window avoids triple-evaluating on a single Ctrl+S.
7
+ export const DEFAULT_DEBOUNCE_MS = 200;
8
+
9
+ // The re-run banner separator. A run of box-drawing horizontals is visually
10
+ // distinct from anything user code or the transform output emits, so the
11
+ // eye can find each re-run boundary in a scrolling terminal.
12
+ const SEPARATOR_CHAR = '─';
13
+ const SEPARATOR_WIDTH = 60;
14
+ const SEPARATOR = SEPARATOR_CHAR.repeat(SEPARATOR_WIDTH);
15
+
16
+ // Origins that resolveInput() reports for non-file sources. `--watch` has
17
+ // nothing to re-read for these, so they are rejected up front.
18
+ const INLINE_ORIGIN = '<inline>';
19
+ const STDIN_ORIGIN = '<stdin>';
20
+
21
+ // `lws eval --watch` needs a real file to watch. resolveInput() reports the
22
+ // resolved absolute path for a file, or one of the sentinel origins above
23
+ // for inline source / stdin. Reject the sentinels with a message that names
24
+ // the actual constraint rather than failing later with a confusing
25
+ // "cannot watch <inline>" deep in chokidar.
26
+ export function assertWatchableEvalOrigin(origin) {
27
+ if (origin === INLINE_ORIGIN || origin === STDIN_ORIGIN) {
28
+ throw new Error('--watch requires a file path; inline source and stdin cannot be watched');
29
+ }
30
+ }
31
+
32
+ // The banner printed before each re-run: a separator, a timestamp, and the
33
+ // path that triggered the re-run. `date` is injected (not read from a
34
+ // global clock) so the unit test can assert a fixed string. `changedPath`
35
+ // is optional: the initial debounced event always carries one, but a
36
+ // caller may omit it.
37
+ export function rerunBanner(date, changedPath) {
38
+ const timestamp = date.toISOString();
39
+ const suffix = changedPath ? ` (changed: ${changedPath})` : '';
40
+ return `${SEPARATOR}\n[lws watch] re-run at ${timestamp}${suffix}\n${SEPARATOR}`;
41
+ }
42
+
43
+ // Some environments don't deliver native filesystem events reliably:
44
+ // containerized Linux CI on overlay/bind-mounted or tmpfs working trees often
45
+ // drops inotify notifications, so a `change` after an edit never arrives and
46
+ // the watcher looks dead. The same gap hits developers running `--watch`
47
+ // inside Docker, on a network mount, or under WSL. chokidar's remedy is
48
+ // `usePolling`, which stat()s on an interval instead of trusting OS events. We
49
+ // keep native events as the default (fast, low CPU — the right call for a
50
+ // local run) and switch to polling only when `CHOKIDAR_USEPOLLING` is set,
51
+ // matching the conventional env-var name even though chokidar 3.x does not
52
+ // read it itself.
53
+ function pollingFromEnv() {
54
+ const value = process.env.CHOKIDAR_USEPOLLING;
55
+ return value === '1' || value === 'true';
56
+ }
57
+
58
+ // Watch `paths` (a single path or an array) and invoke `onChange(changedPath)`
59
+ // after activity settles for `debounceMs`. `add`, `change`, and `unlink` all
60
+ // count as activity: editing a watched file fires `change`; adding or
61
+ // removing a file inside a watched component directory fires `add`/`unlink`.
62
+ //
63
+ // `ignoreInitial: true` suppresses the synthetic `add` events chokidar emits
64
+ // while taking its initial directory census, so the watcher does not fire a
65
+ // spurious re-run the instant it starts. The caller performs the first
66
+ // evaluation itself before wiring this up.
67
+ //
68
+ // `usePolling` defaults to the CHOKIDAR_USEPOLLING env var (see above) but can
69
+ // be passed explicitly.
70
+ //
71
+ // Returns `{ ready, close }`. `ready` resolves on chokidar's `ready` event —
72
+ // the point at which the initial census is complete and subsequent edits are
73
+ // detected as `change`. Callers MUST await `ready` before telling the user the
74
+ // watch is live: with `usePolling`, an edit that lands before the baseline
75
+ // census is absorbed into that baseline and never produces a `change` event,
76
+ // so a "Watching..." banner printed too early is a lie that silently drops the
77
+ // first save. (Native-event backends are more forgiving, which is why this
78
+ // only surfaced once polling was introduced.) `close` clears any pending
79
+ // debounce timer and closes the watcher, stopping the polling intervals so the
80
+ // process exits promptly on SIGINT.
81
+ export function watchPaths({
82
+ paths,
83
+ onChange,
84
+ debounceMs = DEFAULT_DEBOUNCE_MS,
85
+ usePolling = pollingFromEnv(),
86
+ }) {
87
+ const watcher = chokidar.watch(paths, { ignoreInitial: true, usePolling });
88
+ let timer = null;
89
+ let lastPath = null;
90
+
91
+ const schedule = (changedPath) => {
92
+ lastPath = changedPath;
93
+ if (timer !== null) {
94
+ clearTimeout(timer);
95
+ }
96
+ timer = setTimeout(() => {
97
+ timer = null;
98
+ onChange(lastPath);
99
+ }, debounceMs);
100
+ // Don't let a pending debounce timer hold the event loop open on its
101
+ // own. The watch session is kept alive by the signal/disconnect race
102
+ // in the runner, not by this timer.
103
+ timer.unref?.();
104
+ };
105
+
106
+ watcher.on('add', schedule);
107
+ watcher.on('change', schedule);
108
+ watcher.on('unlink', schedule);
109
+
110
+ const ready = new Promise((resolve) => {
111
+ watcher.once('ready', resolve);
112
+ });
113
+
114
+ return {
115
+ ready,
116
+ async close() {
117
+ if (timer !== null) {
118
+ clearTimeout(timer);
119
+ timer = null;
120
+ }
121
+ await watcher.close();
122
+ },
123
+ };
124
+ }