@incremental/watcher 0.1.0 → 0.1.5

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.
package/src/run.ts DELETED
@@ -1,179 +0,0 @@
1
- #!/usr/bin/env node
2
- // `incremental-watcher watch`: the watcher loop. Runs a cycle every --interval
3
- // milliseconds (default 1000), --cycles times (default: until interrupted).
4
- //
5
- // Exit codes: 0 every run task passed; 1 a task failed; 2 usage error; 4 engine or setup error.
6
- import { existsSync, readFileSync } from "node:fs";
7
- import path from "node:path";
8
- import { pathToFileURL } from "node:url";
9
- import { spawnSync } from "node:child_process";
10
- import { defaultEngine } from "@incremental/client";
11
- import { type CycleReport, ConfigError, Session, type TaskDef } from "./session.js";
12
-
13
- export interface WatchOptions {
14
- root: string;
15
- store: string;
16
- tasks: TaskDef[];
17
- intervalMs: number;
18
- cycles: number;
19
- timeoutMs: number;
20
- json: boolean;
21
- }
22
-
23
- export class UsageError extends Error {
24
- constructor(message: string) {
25
- super(message);
26
- this.name = "UsageError";
27
- }
28
- }
29
-
30
- export function loadTasks(file: string): TaskDef[] {
31
- if (!existsSync(file)) throw new UsageError(`no task file at ${file}`);
32
- let raw: unknown;
33
- try {
34
- raw = JSON.parse(readFileSync(file, "utf8"));
35
- } catch (e) {
36
- throw new UsageError(`cannot parse ${file}: ${e instanceof Error ? e.message : String(e)}`);
37
- }
38
- if (!Array.isArray(raw)) throw new UsageError(`${file} must hold a JSON array of tasks`);
39
- const ids = new Set<string>();
40
- return raw.map((t: unknown, i) => {
41
- const o = t as Partial<TaskDef>;
42
- const strings = (v: unknown): v is string[] =>
43
- Array.isArray(v) && v.every((x) => typeof x === "string");
44
- if (
45
- typeof o.id !== "string" ||
46
- o.id === "" ||
47
- !strings(o.command) ||
48
- o.command.length === 0 ||
49
- !strings(o.inputs)
50
- ) {
51
- throw new UsageError(
52
- `task ${i} needs id, command (non-empty string array) and inputs (string array)`,
53
- );
54
- }
55
- if (ids.has(o.id)) throw new UsageError(`duplicate task id ${o.id}`);
56
- ids.add(o.id);
57
- return { id: o.id, command: o.command, inputs: o.inputs };
58
- });
59
- }
60
-
61
- export function parseArgs(argv: string[]): WatchOptions {
62
- const [cmd, ...rest] = argv;
63
- const usage =
64
- "usage: incremental-watcher watch --tasks FILE [--interval MS] [--cycles N] [--json] [--store DIR] [--root DIR] [--timeout MS]";
65
- if (cmd !== "watch") throw new UsageError(usage);
66
- const opts: WatchOptions = {
67
- root: process.cwd(),
68
- store: "",
69
- tasks: [],
70
- intervalMs: 1000,
71
- cycles: 0,
72
- timeoutMs: 600_000,
73
- json: false,
74
- };
75
- let tasksFile: string | null = null;
76
- let storeGiven = false;
77
- for (let i = 0; i < rest.length; i++) {
78
- const a = rest[i] as string;
79
- const value = (): string => {
80
- const v = rest[++i];
81
- if (v === undefined) throw new UsageError(`${a} needs a value`);
82
- return v;
83
- };
84
- const int = (min: number): number => {
85
- const n = Number(value());
86
- if (!Number.isInteger(n) || n < min) throw new UsageError(`${a} needs an integer >= ${min}`);
87
- return n;
88
- };
89
- if (a === "--tasks") {
90
- tasksFile = value();
91
- } else if (a === "--interval") {
92
- opts.intervalMs = int(0);
93
- } else if (a === "--cycles") {
94
- opts.cycles = int(0);
95
- } else if (a === "--timeout") {
96
- opts.timeoutMs = int(1);
97
- } else if (a === "--json") {
98
- opts.json = true;
99
- } else if (a === "--store") {
100
- opts.store = value();
101
- storeGiven = true;
102
- } else if (a === "--root") {
103
- opts.root = value();
104
- } else {
105
- throw new UsageError(`unknown option ${a}`);
106
- }
107
- }
108
- if (tasksFile === null) throw new UsageError(usage);
109
- opts.root = path.resolve(opts.root);
110
- if (!storeGiven)
111
- opts.store = process.env.INCREMENTAL_STORE || path.join(opts.root, ".incremental");
112
- opts.store = path.resolve(opts.store);
113
- opts.tasks = loadTasks(path.resolve(tasksFile));
114
- return opts;
115
- }
116
-
117
- function ensureStore(store: string): void {
118
- if (existsSync(store)) return;
119
- const r = spawnSync(defaultEngine(), ["init", "--store", store], { encoding: "utf8" });
120
- if (r.status !== 0)
121
- throw new UsageError(`cannot create the store at ${store}: ${(r.stderr || "").trim()}`);
122
- }
123
-
124
- function describe(n: number, r: CycleReport): string {
125
- const counts = { pass: 0, fail: 0, error: 0 } as Record<string, number>;
126
- for (const t of r.results) counts[t.outcome] = (counts[t.outcome] ?? 0) + 1;
127
- const why = r.reason === null ? "" : ` (${r.reason})`;
128
- return [
129
- `cycle ${n}: ${r.mode}${why}, stored ${r.stored ?? "none"}, changes ${r.changes.length}`,
130
- ` selected [${r.selected.join(", ")}]: pass ${counts.pass}, fail ${counts.fail}, error ${counts.error}`,
131
- ` ${r.advanced ? `advanced to ${r.headEnd}` : "not advanced"}`,
132
- ].join("\n");
133
- }
134
-
135
- export async function main(argv: string[]): Promise<number> {
136
- let opts: WatchOptions;
137
- try {
138
- opts = parseArgs(argv);
139
- } catch (e) {
140
- process.stderr.write(`${e instanceof Error ? e.message : String(e)}\n`);
141
- return 2;
142
- }
143
- let code = 0;
144
- let session: Session | null = null;
145
- try {
146
- ensureStore(opts.store);
147
- session = new Session({
148
- root: opts.root,
149
- store: opts.store,
150
- tasks: opts.tasks,
151
- timeoutMs: opts.timeoutMs,
152
- });
153
- await session.open();
154
- for (let n = 1; opts.cycles === 0 || n <= opts.cycles; n++) {
155
- const report = await session.cycle();
156
- if (opts.json) process.stdout.write(`${JSON.stringify(report)}\n`);
157
- else process.stdout.write(`${describe(n, report)}\n`);
158
- if (report.results.some((t) => t.outcome === "fail")) code = 1;
159
- // Each cycle walks the whole tree, so the wait is at least ten times that
160
- // walk: the check never takes more than about a tenth of the time, however
161
- // large the repository. The interval is a minimum, not a fixed rate.
162
- const wait = Math.max(opts.intervalMs, 10 * session.lastCheckMs());
163
- if (opts.cycles === 0 || n < opts.cycles) await new Promise((res) => setTimeout(res, wait));
164
- }
165
- return code;
166
- } catch (e) {
167
- const message = e instanceof Error ? e.message : String(e);
168
- process.stderr.write(`incremental watcher: ${message}\n`);
169
- return e instanceof ConfigError || e instanceof UsageError ? 2 : 4;
170
- } finally {
171
- await session?.close();
172
- }
173
- }
174
-
175
- if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
176
- main(process.argv.slice(2)).then((code) => {
177
- process.exitCode = code;
178
- });
179
- }
package/src/session.ts DELETED
@@ -1,336 +0,0 @@
1
- // The watcher loop (spec/adapters/watcher.md). A session holds the event history
2
- // since a store baseline B and turns it into a ChangeSet for `affected`. It mirrors
3
- // the typescript run loop (PLAN 10.4) for observe and advance, with one difference:
4
- // the history is only complete if the watch was running and the tree equalled B
5
- // when it started, so the session advances only from a complete history.
6
- import { spawnSync } from "node:child_process";
7
- import { createHash } from "node:crypto";
8
- import { existsSync, readFileSync, statSync } from "node:fs";
9
- import { createRequire } from "node:module";
10
- import path from "node:path";
11
- import {
12
- connect,
13
- defaultEngine,
14
- repoRoot,
15
- type incremental,
16
- type Change,
17
- type Context,
18
- type Input,
19
- type Observation,
20
- type Outcome,
21
- type Plan,
22
- } from "@incremental/client";
23
- import { relOf, SKIP_DIRS, Watcher, walk } from "./watch.js";
24
-
25
- export class ConfigError extends Error {
26
- constructor(message: string) {
27
- super(message);
28
- this.name = "ConfigError";
29
- }
30
- }
31
-
32
- // A task: a command and the repo-relative files or directories it reads. Inputs
33
- // are declared, not traced: the watcher cannot see what the command reads.
34
- export interface TaskDef {
35
- id: string;
36
- command: string[];
37
- inputs: string[];
38
- }
39
-
40
- export interface SessionOptions {
41
- root: string;
42
- store: string;
43
- tasks: TaskDef[];
44
- timeoutMs: number;
45
- }
46
-
47
- export interface TaskRun {
48
- task: string;
49
- outcome: Outcome;
50
- durationMs: number;
51
- }
52
-
53
- export interface CycleReport {
54
- // "full" runs every task; "incremental" runs the tasks `affected` selected.
55
- mode: "full" | "incremental";
56
- // Why the cycle is full, or null when it is incremental.
57
- reason: string | null;
58
- stored: string | null;
59
- changes: Change[];
60
- plan: Plan | null;
61
- selected: string[];
62
- results: TaskRun[];
63
- advanced: boolean;
64
- headEnd: string;
65
- }
66
-
67
- const require_ = createRequire(import.meta.url);
68
- const WATCHER_RUNNER = `incremental-watcher@${(require_("../../package.json") as { version: string }).version}`;
69
-
70
- function gitSourcePath(): string {
71
- return (
72
- process.env.INCREMENTAL_GIT ||
73
- path.join(repoRoot(), "adapters", "git", "dist", "incremental-git")
74
- );
75
- }
76
-
77
- // The git change source (PLAN 11.7), used only for the baseline check and for
78
- // the advance. The watcher itself runs no git.
79
- interface GitChangeSet {
80
- baseline: string;
81
- head: string;
82
- dirty: boolean;
83
- changes: Change[];
84
- }
85
-
86
- function gitChangeSet(root: string, ref: string): GitChangeSet {
87
- const r = spawnSync(gitSourcePath(), ["changes", "--base", ref, "--root", root], {
88
- encoding: "utf8",
89
- });
90
- if (r.error !== undefined)
91
- throw new Error(`cannot run the git change source: ${r.error.message}`);
92
- if (r.status !== 0)
93
- throw new Error(
94
- `git change source failed (exit ${r.status}): ${(r.stdout || r.stderr || "").trim()}`,
95
- );
96
- return JSON.parse(r.stdout) as GitChangeSet;
97
- }
98
-
99
- // The context (PLAN 8.4). The watcher observes no tool, lockfile or probe, so the
100
- // reserved keys are constant and caps are all false. In balanced mode that makes
101
- // any change to a path that is not a task input a fallback (P6, P7), which is sound.
102
- export function contextFor(): Context {
103
- return {
104
- lockfile: "absent",
105
- tsconfig: "absent",
106
- pkgjson: "absent",
107
- runner: WATCHER_RUNNER,
108
- node: process.version,
109
- fmt: 1,
110
- caps: { probes: false, dirs: false, env: false },
111
- };
112
- }
113
-
114
- type FileInput = Extract<Input, { kind: "file" }>;
115
-
116
- function sha256(data: Buffer): string {
117
- return createHash("sha256").update(data).digest("hex");
118
- }
119
-
120
- // The file inputs of a task: each declared path, directories expanded. Missing
121
- // paths contribute nothing (a later creation is an added path, which falls back).
122
- export function inputsOf(root: string, task: TaskDef): FileInput[] {
123
- const files = new Map<string, FileInput>();
124
- for (const entry of task.inputs) {
125
- const abs = path.resolve(root, entry);
126
- const rel = relOf(root, abs);
127
- if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
128
- throw new ConfigError(`task ${task.id}: input ${entry} is outside the repository`);
129
- }
130
- if (rel.split("/").some((s) => SKIP_DIRS.has(s))) {
131
- throw new ConfigError(`task ${task.id}: input ${entry} is under an ignored directory`);
132
- }
133
- if (existsSync(abs)) {
134
- const st = statSync(abs);
135
- const kinds: Map<string, string> = st.isDirectory()
136
- ? walk(root, abs)
137
- : new Map([[rel, "file"]]);
138
- for (const [child, kind] of kinds) {
139
- if (kind === "file") {
140
- files.set(child, {
141
- kind: "file",
142
- path: child,
143
- hash: sha256(readFileSync(path.join(root, child))),
144
- });
145
- }
146
- }
147
- }
148
- }
149
- return [...files.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
150
- }
151
-
152
- export class Session {
153
- private client: incremental | null = null;
154
- private readonly watcher: Watcher;
155
- // The baseline the event history is complete since, or null.
156
- private base: string | null = null;
157
- // The first cycle of a session runs everything: a restart has no history.
158
- private first = true;
159
-
160
- constructor(private readonly opts: SessionOptions) {
161
- this.watcher = new Watcher(opts.root);
162
- }
163
-
164
- // Connects to the store and opens a watch window against the stored baseline.
165
- async open(): Promise<void> {
166
- this.client = await connect({
167
- store: this.opts.store,
168
- root: this.opts.root,
169
- command: [defaultEngine(), "serve"],
170
- timeoutMs: 60_000,
171
- });
172
- await this.arm();
173
- }
174
-
175
- async close(): Promise<void> {
176
- this.watcher.stop();
177
- await this.client?.close();
178
- this.client = null;
179
- }
180
-
181
- // Duration of the last full check of the tree, in milliseconds.
182
- lastCheckMs(): number {
183
- return this.watcher.lastWalkMs;
184
- }
185
-
186
- // Events the watcher has recorded since the window started, for callers that
187
- // want to know whether a cycle has work to do.
188
- pending(): number {
189
- return this.watcher.state().changes.length;
190
- }
191
-
192
- // Reports an event loss from outside the watcher (for example a dropped
193
- // notification). The next cycle runs everything.
194
- reportLoss(reason: string): void {
195
- this.watcher.loss(reason);
196
- }
197
-
198
- // Starts a new window. The history is complete only if the tree equalled the
199
- // stored baseline when the window started, and the window is then the baseline.
200
- private async arm(): Promise<void> {
201
- this.watcher.start();
202
- const stored = (await this.need().baseline()).baseline;
203
- this.base = null;
204
- if (stored === null) return;
205
- let cs: GitChangeSet;
206
- try {
207
- cs = gitChangeSet(this.opts.root, stored);
208
- } catch {
209
- return;
210
- }
211
- if (cs.baseline === stored && cs.changes.length === 0 && !cs.dirty) this.base = stored;
212
- }
213
-
214
- private need(): incremental {
215
- if (this.client === null) throw new Error("the session is not open");
216
- return this.client;
217
- }
218
-
219
- // One cycle: the ChangeSet since the stored baseline, `affected`, the selected
220
- // tasks run and observed, then advance if the history was complete.
221
- async cycle(): Promise<CycleReport> {
222
- const client = this.need();
223
- const { root } = this.opts;
224
- const stored = (await client.baseline()).baseline;
225
- const startHead = gitChangeSet(root, "HEAD").head;
226
- const gen = this.watcher.generation;
227
- const state = this.watcher.state();
228
- const complete = this.base !== null && this.base === stored && state.lost === null;
229
-
230
- let reason: string | null = null;
231
- if (this.first) reason = "no_history";
232
- else if (this.base === null) reason = "not_watching_since_baseline";
233
- else if (this.base !== stored) reason = "baseline_moved";
234
- else if (state.lost !== null) reason = `watcher_lost: ${state.lost}`;
235
-
236
- let plan: Plan | null = null;
237
- if (reason === null && stored !== null) {
238
- plan = await client.affected(
239
- { baseline: stored, changes: state.changes },
240
- {
241
- baseline: stored,
242
- context: contextFor(),
243
- declared_tasks: this.opts.tasks.map((t) => t.id),
244
- verify: false,
245
- policy: "balanced",
246
- },
247
- );
248
- if (plan.fallback !== null) reason = `${plan.fallback.reason}`;
249
- const declared = new Set(this.opts.tasks.map((t) => t.id));
250
- if (reason === null && plan.tasks.some((t) => !declared.has(t.id)))
251
- reason = "plan_unknown_task";
252
- }
253
-
254
- const full = reason !== null || stored === null;
255
- const selectedIds = full
256
- ? this.opts.tasks.map((t) => t.id)
257
- : (plan?.tasks ?? []).map((t) => t.id);
258
- const selected = this.opts.tasks.filter((t) => selectedIds.includes(t.id));
259
-
260
- const results: TaskRun[] = [];
261
- const observations: Observation[] = [];
262
- const obsBaseline = stored ?? startHead;
263
- for (const task of selected) {
264
- const inputs = inputsOf(root, task);
265
- const run = runTask(root, task, this.opts.timeoutMs);
266
- results.push({ task: task.id, ...run });
267
- observations.push({
268
- task: task.id,
269
- baseline: obsBaseline,
270
- dirty: true,
271
- context: contextFor(),
272
- inputs,
273
- outputs: [],
274
- outcome: run.outcome,
275
- duration_ms: run.durationMs,
276
- });
277
- }
278
-
279
- const end = gitChangeSet(root, "HEAD");
280
- // The tree is clean at HEAD, the window covered the baseline, and no event
281
- // arrived during the run: the runs saw exactly the tree that the baseline names.
282
- const treeClean =
283
- complete && !end.dirty && end.head === startHead && this.watcher.generation === gen;
284
- // Observations are reusable only from a clean tree (dirty ones are never trusted).
285
- for (const o of observations) o.dirty = !treeClean;
286
- if (observations.length > 0) await client.observeMany(observations);
287
-
288
- const allRan = results.every((r) => r.outcome !== "error");
289
- const canAdvance = treeClean && stored !== null && allRan;
290
- let advanced = false;
291
- if (canAdvance && end.head !== stored) {
292
- await client.advance(end.head, stored);
293
- advanced = true;
294
- this.base = end.head;
295
- this.watcher.rebase();
296
- }
297
- // A full cycle that did not advance starts a new window, so the next cycle can
298
- // be incremental again if the tree equals the stored baseline.
299
- if (full && !advanced) await this.arm();
300
-
301
- const report: CycleReport = {
302
- mode: full ? "full" : "incremental",
303
- reason,
304
- stored,
305
- changes: state.changes,
306
- plan,
307
- selected: selected.map((t) => t.id),
308
- results,
309
- advanced,
310
- headEnd: end.head,
311
- };
312
- this.first = false;
313
- return report;
314
- }
315
- }
316
-
317
- // Runs one task command in the repository. A command that cannot start, or is
318
- // killed, is an error, never a pass.
319
- export function runTask(
320
- root: string,
321
- task: TaskDef,
322
- timeoutMs: number,
323
- ): { outcome: Outcome; durationMs: number } {
324
- const started = Date.now();
325
- const [cmd, ...args] = task.command;
326
- if (cmd === undefined) throw new ConfigError(`task ${task.id}: empty command`);
327
- const r = spawnSync(cmd, args, {
328
- cwd: root,
329
- encoding: "utf8",
330
- timeout: timeoutMs,
331
- maxBuffer: 64 * 1024 * 1024,
332
- });
333
- const durationMs = Date.now() - started;
334
- if (r.error !== undefined || r.signal !== null) return { outcome: "error", durationMs };
335
- return { outcome: r.status === 0 ? "pass" : "fail", durationMs };
336
- }