rollbridge 0.1.73 → 0.1.74

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.
Files changed (67) hide show
  1. package/README.md +63 -10
  2. package/TODO.md +13 -0
  3. package/changelog.d/20261025-guardian-re-register-dead-generation.md +13 -0
  4. package/changelog.d/20261026-stale-committed-generation-transition-recovery.md +1 -0
  5. package/changelog.d/20261104-compose-service-units.md +21 -0
  6. package/changelog.d/20261105-owner-mutation-lease-diagnostics.md +20 -0
  7. package/changelog.d/20261106-release-dependency-boot-budgets.md +32 -0
  8. package/changelog.d/20261109-path-filtered-builds.md +11 -0
  9. package/changelog.d/20261110-default-boot-budget-above-measured-startup.md +26 -0
  10. package/changelog.d/20261111-contention-sensitive-daemon-specs.md +27 -0
  11. package/changelog.d/20261113-bounded-nonblocking-retirement.md +5 -0
  12. package/changelog.d/20261115-bound-draining-release-groups.md +62 -0
  13. package/changelog.d/20261115-restore-deploy-refuses-held-generation.md +27 -0
  14. package/changelog.d/20261115-wedged-generation-escalation.md +44 -0
  15. package/changelog.d/20261116-bounded-explicit-stop-retirement.md +30 -0
  16. package/changelog.d/20261116-config-json-canonical-shape.md +11 -0
  17. package/changelog.d/20261116-drain-specs-gate-the-retirement-record.md +29 -0
  18. package/changelog.d/20261116-guardian-version-handoff.md +37 -0
  19. package/changelog.d/20261116-reclaim-dead-owner-mutation.md +7 -0
  20. package/changelog.d/20261117-activate-before-incumbent-retirement.md +1 -0
  21. package/changelog.d/20261117-activation-path-drain-deadline.md +35 -0
  22. package/changelog.d/20261117-stop-companion-after-retired-dependency.md +7 -0
  23. package/changelog.d/20261118-incumbent-retirement-authority-guard.md +1 -0
  24. package/changelog.d/20261118-owner-retirement-no-guardian-bound.md +19 -0
  25. package/changelog.d/20261118-shutdown-retirement-bound-restored.md +31 -0
  26. package/docs/cli.md +128 -3
  27. package/docs/compose-services.md +222 -0
  28. package/docs/config.md +177 -6
  29. package/docs/troubleshooting.md +97 -6
  30. package/docs/velocious.md +1 -1
  31. package/docs/workers.md +11 -0
  32. package/examples/tensorbuzz.com.js +3 -2
  33. package/package.json +1 -1
  34. package/src/cli.js +68 -2
  35. package/src/compose-unit.js +725 -0
  36. package/src/config.js +346 -8
  37. package/src/daemon.js +411 -78
  38. package/src/doctor.js +74 -0
  39. package/src/drain-policy.js +252 -0
  40. package/src/guardian-client.js +68 -23
  41. package/src/health.js +99 -8
  42. package/src/managed-process.js +198 -45
  43. package/src/process-guardian.js +212 -37
  44. package/src/process-memory.js +58 -23
  45. package/src/process-order.js +26 -0
  46. package/src/release-group.js +438 -45
  47. package/tensorbuzz.yml +20 -1
  48. package/test/completion.test.js +5 -2
  49. package/test/compose-config.test.js +160 -0
  50. package/test/compose-docker.test.js +297 -0
  51. package/test/compose-unit.test.js +415 -0
  52. package/test/config-validation.test.js +135 -5
  53. package/test/drain-policy.test.js +328 -0
  54. package/test/fixtures/deferred-boot-app.js +106 -0
  55. package/test/fixtures/gated-app.js +50 -0
  56. package/test/guardian-client.test.js +119 -5
  57. package/test/health.test.js +74 -1
  58. package/test/managed-process.test.js +260 -24
  59. package/test/owner-recovery.test.js +125 -21
  60. package/test/owner-replacement.test.js +175 -14
  61. package/test/process-memory.test.js +47 -1
  62. package/test/release-group.test.js +408 -2
  63. package/test/rollbridge.test.js +774 -72
  64. package/test/shutdown-completion.test.js +119 -0
  65. package/test/shutdown-retirement-bound.test.js +162 -0
  66. package/test/support/process.js +3 -1
  67. package/test/tensorbuzz-config.test.js +228 -0
@@ -176,6 +176,119 @@ test("shutdown keeps daemon services alive until release-owned dependents stop",
176
176
  }
177
177
  })
178
178
 
179
+ test("shutdown returns after the non-blocking drain budget instead of waiting for a worker", async () => {
180
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-shutdown-non-blocking-drain-"))
181
+ const socketPath = path.join(root, "control.sock")
182
+ const readyPath = path.join(root, "ready")
183
+ const processCommand = `${JSON.stringify(process.execPath)} -e ${JSON.stringify(`process.on('SIGTERM', () => {}); require("node:fs").writeFileSync(${JSON.stringify(readyPath)}, "ready"); setInterval(() => {}, 1000)`)}`
184
+ const config = buildConfig(socketPath, {
185
+ companion: {command: processCommand, gracefulStopMs: "indefinite", id: "worker", nonBlockingDrain: true, policy: "companion"}
186
+ })
187
+ config.proxy.nonBlockingDrainTimeoutMs = 25
188
+ const daemon = new RollbridgeDaemon({config, logger: () => {}})
189
+ let workerPid
190
+
191
+ try {
192
+ await daemon.start()
193
+ await daemon.deploy({releaseId: "v1", releasePath: root, revision: "v1"})
194
+ await waitForFile(readyPath)
195
+ workerPid = daemon.activeRelease?.getProcess("worker")?.pid
196
+
197
+ expect(typeof workerPid).toBe("number")
198
+
199
+ let timer
200
+ try {
201
+ await Promise.race([
202
+ daemon.shutdown(),
203
+ new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("shutdown waited past its retirement budget")), 1000) })
204
+ ])
205
+ } finally {
206
+ clearTimeout(timer)
207
+ }
208
+
209
+ let workerGroupAlive = true
210
+ try {
211
+ process.kill(-/** @type {number} */ (workerPid), 0)
212
+ } catch {
213
+ workerGroupAlive = false
214
+ }
215
+ expect(workerGroupAlive).toBe(true)
216
+ } finally {
217
+ if (workerPid) {
218
+ try { process.kill(-workerPid, "SIGKILL") } catch (_error) { /* Exact fixture process already exited. */ }
219
+ }
220
+ await daemon.shutdown().catch(() => {})
221
+ await fs.rm(root, {force: true, recursive: true})
222
+ }
223
+ })
224
+
225
+ test("retiring an owner without a guardian stops waiting for its indefinite-window companion", async () => {
226
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-retirement-no-guardian-bound-"))
227
+ const socketPath = path.join(root, "control.sock")
228
+ const readyPath = path.join(root, "ready")
229
+ const processCommand = `${JSON.stringify(process.execPath)} -e ${JSON.stringify(`process.on('SIGTERM', () => {}); require("node:fs").writeFileSync(${JSON.stringify(readyPath)}, "ready"); setInterval(() => {}, 1000)`)}`
230
+ const config = buildConfig(socketPath, {
231
+ companion: {command: processCommand, gracefulStopMs: "indefinite", id: "worker", policy: "companion"}
232
+ })
233
+ config.proxy.nonBlockingDrainTimeoutMs = 25
234
+ /** @type {{data: Record<string, import("../src/json.js").JsonValue>, message: string}[]} */
235
+ const events = []
236
+ /** @type {() => void} */
237
+ let signalResidue = () => {}
238
+ const residue = new Promise((resolve) => { signalResidue = () => resolve(undefined) })
239
+ const daemon = new RollbridgeDaemon({config, logger: (message, data = {}) => {
240
+ events.push({data, message})
241
+ if (message === "release stop gave up waiting for a retiring process") signalResidue()
242
+ }})
243
+ let workerPid
244
+
245
+ try {
246
+ await daemon.start()
247
+ await daemon.deploy({releaseId: "v1", releasePath: root, revision: "v1"})
248
+ await waitForFile(readyPath)
249
+ workerPid = daemon.activeRelease?.getProcess("worker")?.pid
250
+
251
+ expect(typeof workerPid).toBe("number")
252
+
253
+ await daemon.retireOwner({attestation: `sha256:${"a".repeat(64)}`})
254
+
255
+ // Without a guardian nothing else retires these processes, so the retirement's own stop must
256
+ // reach its budget: the log line is the event that proves it stopped waiting.
257
+ let timer
258
+ try {
259
+ await Promise.race([
260
+ residue,
261
+ new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("retirement never stopped waiting for its companion")), 5000) })
262
+ ])
263
+ } finally {
264
+ clearTimeout(timer)
265
+ }
266
+
267
+ const retired = daemon.status().releases.find((release) => release.releaseId === "v1")
268
+
269
+ expect(retired?.state).toBe("stopped")
270
+ expect(retired?.processes.find((processEntry) => processEntry.id === "worker")?.state).toBe("stopped")
271
+ expect(events.find((event) => event.message === "release stop gave up waiting for a retiring process")?.data).toMatchObject({processId: "worker", releaseId: "v1", timeoutMs: 25})
272
+
273
+ // Stopping the wait is not stopping the process: the supervisor must not kill it.
274
+ let workerGroupAlive = true
275
+
276
+ try {
277
+ process.kill(-/** @type {number} */ (workerPid), 0)
278
+ } catch {
279
+ workerGroupAlive = false
280
+ }
281
+
282
+ expect(workerGroupAlive).toBe(true)
283
+ } finally {
284
+ if (workerPid) {
285
+ try { process.kill(-workerPid, "SIGKILL") } catch (_error) { /* Exact fixture process already exited. */ }
286
+ }
287
+ await daemon.shutdown().catch(() => {})
288
+ await fs.rm(root, {force: true, recursive: true})
289
+ }
290
+ })
291
+
179
292
  test("external-owner retirement releases listeners before a long-draining companion exits", async () => {
180
293
  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-owner-retirement-"))
181
294
  const socketPath = path.join(root, "rollbridge.sock")
@@ -401,6 +514,12 @@ function rawConfig(socketPath) {
401
514
  * @returns {Promise<void>} Resolves when the file appears.
402
515
  */
403
516
  async function waitForFile(filePath) {
517
+ try {
518
+ await fs.access(filePath)
519
+ return
520
+ } catch {
521
+ // The file may be created after the watcher is installed.
522
+ }
404
523
  const watcher = fs.watch(path.dirname(filePath))
405
524
 
406
525
  try {
@@ -0,0 +1,162 @@
1
+ // @ts-check
2
+
3
+ import fs from "node:fs/promises"
4
+ import os from "node:os"
5
+ import path from "node:path"
6
+ import {describe, expect, test} from "@velocious/testing"
7
+ import {fileURLToPath} from "node:url"
8
+ import {normalizeConfig} from "../src/config.js"
9
+ import {sendControlCommand} from "../src/control-client.js"
10
+ import RollbridgeDaemon from "../src/daemon.js"
11
+
12
+ describe("shutdown-retirement-bound", () => {
13
+
14
+ const dummyAppPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "fixtures", "dummy-app.js")
15
+ const wedgedCommand = `${JSON.stringify(process.execPath)} -e ${JSON.stringify("process.on(\"SIGTERM\", () => {}); setInterval(() => {}, 50)")}`
16
+
17
+ /**
18
+ * Waits for a shutdown to finish, without ever waiting past the retirement budget it is supposed to
19
+ * enforce.
20
+ * @param {RollbridgeDaemon} daemon - Daemon to shut down.
21
+ * @param {number} watchdogMs - Watchdog that fails the wait instead of hanging forever.
22
+ * @returns {Promise<"returned" | "wedged">} Which side of the race finished first.
23
+ */
24
+ async function raceShutdown(daemon, watchdogMs) {
25
+ return await Promise.race([
26
+ daemon.shutdown().then(() => /** @type {const} */ ("returned")),
27
+ new Promise((resolve) => setTimeout(() => resolve(/** @type {const} */ ("wedged")), watchdogMs))
28
+ ])
29
+ }
30
+
31
+ /**
32
+ * @param {number} pid - Process group id to probe.
33
+ * @returns {boolean} True when the process group is still alive.
34
+ */
35
+ function processGroupAlive(pid) {
36
+ try {
37
+ process.kill(-pid, 0)
38
+ return true
39
+ } catch {
40
+ return false
41
+ }
42
+ }
43
+
44
+ test("shutdown gives up waiting for a release process that ignores its stop signal and still finishes its own cleanup", async () => {
45
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-shutdown-release-retirement-"))
46
+ const socketPath = path.join(root, "control.sock")
47
+ const statePath = path.join(root, "state.json")
48
+ const config = normalizeConfig({
49
+ ...rawConfig(socketPath),
50
+ processes: [
51
+ {command: wedgedCommand, gracefulStopMs: "indefinite", id: "wedged", policy: "companion"},
52
+ ...rawConfig(socketPath).processes
53
+ ],
54
+ proxy: {...rawConfig(socketPath).proxy, nonBlockingDrainTimeoutMs: 400},
55
+ statePath
56
+ })
57
+ /** @type {{message: string}[]} */
58
+ const logs = []
59
+ const daemon = new RollbridgeDaemon({config, logger: (message) => { logs.push({message}) }})
60
+ /** @type {RollbridgeDaemon | undefined} */
61
+ let replacement
62
+ /** @type {number | undefined} */
63
+ let wedgedPid
64
+
65
+ try {
66
+ await daemon.start()
67
+ await daemon.deploy({releaseId: "v1", releasePath: root, revision: "v1"})
68
+
69
+ wedgedPid = daemon.status().releases.find(({releaseId}) => releaseId === "v1")?.processes.find(({id}) => id === "wedged")?.pid
70
+ expect(typeof wedgedPid).toBe("number")
71
+
72
+ // The bound is the assertion: unbudgeted, this stop waited forever, so the daemon stayed alive
73
+ // with its control socket already unlinked and its generation still held — the wedged daemon
74
+ // STOE-2275 measured behind 4,800 `connect ECONNREFUSED` proxy errors.
75
+ expect(await raceShutdown(daemon, 6000)).toBe("returned")
76
+ expect(logs.some(({message}) => message === "release stop gave up waiting for a retiring process")).toBe(true)
77
+
78
+ // Giving up is not killing: the tracked pid is the shell wrapper, which does take the signal, but
79
+ // the process group it started is left alive for the operator to inspect.
80
+ expect(processGroupAlive(/** @type {number} */ (wedgedPid))).toBe(true)
81
+
82
+ // The shutdown completed, so it removed its endpoint and its state instead of hanging behind them.
83
+ await expect(fs.stat(socketPath)).rejects.toMatchObject({code: "ENOENT"})
84
+ await expect(fs.stat(statePath)).rejects.toMatchObject({code: "ENOENT"})
85
+
86
+ // A new owner can take the endpoint immediately: the wedged daemon is what made `rollbridge
87
+ // rollback` and `restart` unreachable for seven minutes.
88
+ replacement = new RollbridgeDaemon({config, logger: () => {}})
89
+ await replacement.start()
90
+ expect((await sendControlCommand({command: {command: "status"}, path: socketPath})).application).toBe("shutdown-retirement-bound")
91
+ } finally {
92
+ await replacement?.shutdown().catch(() => undefined)
93
+
94
+ if (wedgedPid !== undefined) {
95
+ try {
96
+ process.kill(-wedgedPid, "SIGKILL")
97
+ } catch {
98
+ // Already gone.
99
+ }
100
+ }
101
+
102
+ await fs.rm(root, {force: true, recursive: true})
103
+ }
104
+ })
105
+
106
+ test("shutdown stops waiting for a daemon service whose graceful window is indefinite", async () => {
107
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-shutdown-service-retirement-"))
108
+ const socketPath = path.join(root, "control.sock")
109
+ const config = normalizeConfig({
110
+ ...rawConfig(socketPath),
111
+ processes: [
112
+ {command: wedgedCommand, gracefulStopMs: "indefinite", id: "coordinator", policy: "service"},
113
+ ...rawConfig(socketPath).processes
114
+ ],
115
+ proxy: {...rawConfig(socketPath).proxy, nonBlockingDrainTimeoutMs: 400}
116
+ })
117
+ const daemon = new RollbridgeDaemon({config, logger: () => {}})
118
+ /** @type {number | undefined} */
119
+ let coordinatorPid
120
+
121
+ try {
122
+ await daemon.start()
123
+ await daemon.deploy({releaseId: "v1", releasePath: root, revision: "v1"})
124
+
125
+ coordinatorPid = daemon.status().services.find(({id}) => id === "coordinator")?.process.pid
126
+ expect(typeof coordinatorPid).toBe("number")
127
+
128
+ expect(await raceShutdown(daemon, 6000)).toBe("returned")
129
+ expect(processGroupAlive(/** @type {number} */ (coordinatorPid))).toBe(true)
130
+ await expect(fs.stat(socketPath)).rejects.toMatchObject({code: "ENOENT"})
131
+ } finally {
132
+ if (coordinatorPid !== undefined) {
133
+ try {
134
+ process.kill(-coordinatorPid, "SIGKILL")
135
+ } catch {
136
+ // Already gone.
137
+ }
138
+ }
139
+
140
+ await fs.rm(root, {force: true, recursive: true})
141
+ }
142
+ })
143
+
144
+ /**
145
+ * @param {string} socketPath - Control socket path.
146
+ * @returns {{application: string, control: {path: string}, processes: Record<string, import("../src/json.js").JsonValue>[], proxy: {forceStopTimeoutMs: number, healthPath: string, healthTimeoutMs: number, host: string, port: number}}} Raw config.
147
+ */
148
+ function rawConfig(socketPath) {
149
+ return {
150
+ application: "shutdown-retirement-bound",
151
+ control: {path: socketPath},
152
+ processes: [{
153
+ command: `${JSON.stringify(process.execPath)} ${JSON.stringify(dummyAppPath)}`,
154
+ health: {intervalMs: 25, path: "/ping", timeoutMs: 3000},
155
+ id: "web",
156
+ policy: "proxied",
157
+ port: {from: 0, to: 0}
158
+ }],
159
+ proxy: {forceStopTimeoutMs: 500, healthPath: "/ping", healthTimeoutMs: 3000, host: "127.0.0.1", port: 0}
160
+ }
161
+ }
162
+ })
@@ -24,7 +24,9 @@ export function isProcessRunning(pid) {
24
24
 
25
25
  return state !== "Z" && state !== "X"
26
26
  } catch (error) {
27
- if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return false
27
+ // The pid can be reaped between the signal probe and this read, and procfs reports that as
28
+ // ESRCH rather than ENOENT. Both mean the same thing here: there is no process left to wait on.
29
+ if (error && typeof error === "object" && "code" in error && (error.code === "ENOENT" || error.code === "ESRCH")) return false
28
30
  throw error
29
31
  }
30
32
  }
@@ -0,0 +1,228 @@
1
+ // @ts-check
2
+
3
+ import {execFile} from "node:child_process"
4
+ import fs from "node:fs/promises"
5
+ import path from "node:path"
6
+ import {describe, expect, test} from "@velocious/testing"
7
+ import {fileURLToPath} from "node:url"
8
+ import {promisify} from "node:util"
9
+
10
+ describe("tensorbuzz-config", () => {
11
+
12
+ const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
13
+ const execFileAsync = promisify(execFile)
14
+
15
+ /**
16
+ * @typedef {object} PathRule
17
+ * @property {boolean} negated True when the rule carves the paths it matches out of the lane.
18
+ * @property {string} pattern Rule body without its YAML quotes and without the `!` prefix.
19
+ * @property {RegExp} regexp Matcher compiled from the rule body.
20
+ * @property {string} raw Rule exactly as declared in tensorbuzz.yml, quotes included.
21
+ */
22
+
23
+ /**
24
+ * @typedef {object} PathDecision
25
+ * @property {string} filePath Repo-relative path the decision was taken on.
26
+ * @property {string} matchedPattern Last rule that matched, empty when no rule matched.
27
+ * @property {boolean} skipped True when the last matching rule negates the path.
28
+ */
29
+
30
+ /**
31
+ * @typedef {object} GateInput
32
+ * @property {string[]} readPaths Paths `npm run all-checks` opens: the suite and the linters read
33
+ * these, so carving any of them out of the lane would skip a check that the change can break.
34
+ * @property {string[]} skippedPaths Paths the lane must not need: Markdown the gate never opens.
35
+ */
36
+
37
+ const GATE_INPUTS = [
38
+ "src/daemon.js",
39
+ "src/process-guardian.js",
40
+ "test/rollbridge.test.js",
41
+ "test/fixtures/dummy-app.js",
42
+ "bin/rollbridge",
43
+ "examples/tensorbuzz.com.js",
44
+ "package.json",
45
+ "package-lock.json",
46
+ "tsconfig.json",
47
+ "eslint.config.js",
48
+ ".npmignore",
49
+ "LICENSE",
50
+ "compose.yml",
51
+ "tensorbuzz.yml"
52
+ ]
53
+
54
+ const MARKDOWN_PATHS = [
55
+ "README.md",
56
+ "AGENTS.md",
57
+ "docs/tensorbuzz-runbook.md",
58
+ "docs/releasing.md",
59
+ "changelog.d/20261109-path-filtered-builds.md"
60
+ ]
61
+
62
+ /**
63
+ * Reads the root `paths` rules out of tensorbuzz.yml.
64
+ * @param {string} configText Full tensorbuzz.yml contents.
65
+ * @returns {PathRule[]} Rules in declaration order.
66
+ */
67
+ function readPathRules(configText) {
68
+ const lines = configText.split("\n")
69
+ const start = lines.findIndex((line) => line.trim() === "paths:")
70
+
71
+ if (start < 0) return []
72
+
73
+ /** @type {PathRule[]} */
74
+ const rules = []
75
+
76
+ for (const line of lines.slice(start + 1)) {
77
+ const entry = line.trim()
78
+
79
+ if (!entry.startsWith("- ")) break
80
+ if (!entry) continue
81
+
82
+ const raw = entry.slice(2).trim()
83
+ const quoted = raw.startsWith("\"") && raw.endsWith("\"") && raw.length > 1
84
+ const body = quoted ? raw.slice(1, -1) : raw
85
+ const negated = body.startsWith("!")
86
+
87
+ rules.push({
88
+ negated,
89
+ pattern: negated ? body.slice(1) : body,
90
+ raw,
91
+ regexp: compileRuleRegExp(negated ? body.slice(1) : body)
92
+ })
93
+ }
94
+
95
+ return rules
96
+ }
97
+
98
+ /**
99
+ * Compiles a `paths` glob the way TensorBuzz does, for the syntax this config declares: `**`
100
+ * crosses segments, `*` stays inside one segment, a rule containing `/` is anchored at the repo
101
+ * root while a bare name matches at any depth, and a matched directory covers everything below
102
+ * it. The `supported glob syntax` test keeps the config inside that subset.
103
+ * @param {string} pattern Rule body without the `!` prefix.
104
+ * @returns {RegExp} Anchored matcher for one repo-relative path.
105
+ */
106
+ function compileRuleRegExp(pattern) {
107
+ const body = pattern.replace(/^\/+/, "").replace(/\/+$/, "")
108
+ const segments = body.split("/")
109
+ let source = body.includes("/") ? "" : "(?:[^/]+/)*"
110
+
111
+ for (let index = 0; index < segments.length; index += 1) {
112
+ const segment = segments[index]
113
+ const isLast = index === segments.length - 1
114
+
115
+ if (segment === "**") {
116
+ source += isLast ? ".*" : "(?:.*/)?"
117
+
118
+ continue
119
+ }
120
+
121
+ source += segment.split("*").map(escapeForRegExp).join("[^/]*")
122
+
123
+ if (!isLast) source += "/"
124
+ }
125
+
126
+ if (!body.endsWith("**")) source += "(?:/.*)?"
127
+
128
+ return new RegExp(`^${source}$`)
129
+ }
130
+
131
+ /**
132
+ * @param {string} text Literal text to make regexp-safe.
133
+ * @returns {string} Escaped text.
134
+ */
135
+ function escapeForRegExp(text) {
136
+ return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
137
+ }
138
+
139
+ /**
140
+ * Applies ordered rules to one path; the last match wins, exactly like TensorBuzz.
141
+ * @param {{filePath: string, rules: PathRule[]}} args Path and the declared rules.
142
+ * @returns {PathDecision} Whether the lane runs for that path.
143
+ */
144
+ function decidePath({filePath, rules}) {
145
+ /** @type {PathRule | null} */
146
+ let lastMatch = null
147
+
148
+ for (const rule of rules) {
149
+ if (rule.regexp.test(filePath)) lastMatch = rule
150
+ }
151
+
152
+ return {
153
+ filePath,
154
+ matchedPattern: lastMatch ? lastMatch.pattern : "",
155
+ skipped: lastMatch !== null && lastMatch.negated
156
+ }
157
+ }
158
+
159
+ /**
160
+ * @returns {Promise<PathRule[]>} Rules parsed from the repository's tensorbuzz.yml.
161
+ */
162
+ async function declaredPathRules() {
163
+ return readPathRules(await fs.readFile(path.join(repoRoot, "tensorbuzz.yml"), "utf8"))
164
+ }
165
+
166
+ test("tensorbuzz.yml declares a paths block that defaults to running the lane", async () => {
167
+ const rules = await declaredPathRules()
168
+
169
+ expect(rules.length >= 2).toBeTruthy()
170
+ expect(rules[0].pattern).toBe("**")
171
+ expect(rules[0].negated).toBe(false)
172
+
173
+ const firstNegation = rules.findIndex((rule) => rule.negated)
174
+
175
+ expect(firstNegation > 0).toBeTruthy()
176
+
177
+ // A positive rule after a negation would re-admit every path the negation carved out, because
178
+ // the last match wins.
179
+ expect(rules.slice(firstNegation).filter((rule) => !rule.negated).map((rule) => rule.raw)).toEqual([])
180
+ })
181
+
182
+ test("every paths rule is a quoted glob the config validator accepts", async () => {
183
+ const rules = await declaredPathRules()
184
+
185
+ // An unquoted `!x` is a YAML tag, not a string, and the validator rejects the whole config.
186
+ expect(rules.map((rule) => rule.raw).filter((raw) => !raw.startsWith("\""))).toEqual([])
187
+ expect(rules.map((rule) => rule.pattern).filter((pattern) => !/^[A-Za-z0-9_./*-]+$/.test(pattern))).toEqual([])
188
+ expect(rules.map((rule) => rule.pattern).filter((pattern) => pattern.length < 1)).toEqual([])
189
+ })
190
+
191
+ test("a delivery that changes only Markdown is filtered out of the lane", async () => {
192
+ const rules = await declaredPathRules()
193
+
194
+ for (const filePath of MARKDOWN_PATHS) {
195
+ const decision = decidePath({filePath, rules})
196
+
197
+ expect({context: filePath, skipped: decision.skipped}).toEqual({context: filePath, skipped: true})
198
+ }
199
+ })
200
+
201
+ test("every path the gate reads stays inside the lane", async () => {
202
+ const rules = await declaredPathRules()
203
+
204
+ for (const filePath of GATE_INPUTS) {
205
+ const decision = decidePath({filePath, rules})
206
+
207
+ expect({context: filePath, matchedPattern: decision.matchedPattern, skipped: decision.skipped})
208
+ .toEqual({context: filePath, matchedPattern: "**", skipped: false})
209
+ }
210
+ })
211
+
212
+ test("the declared rules partition every tracked path between the lane and the skip set", async () => {
213
+ const rules = await declaredPathRules()
214
+ const {stdout} = await execFileAsync("git", ["ls-files"], {cwd: repoRoot})
215
+ const trackedPaths = stdout.split("\n").filter((line) => line.length > 0)
216
+
217
+ const skipped = trackedPaths.filter((filePath) => decidePath({filePath, rules}).skipped)
218
+ const runs = trackedPaths.filter((filePath) => !decidePath({filePath, rules}).skipped)
219
+
220
+ expect(skipped.length > 0).toBeTruthy()
221
+ expect(runs.length > 0).toBeTruthy()
222
+
223
+ // Only Markdown may be carved out: any other tracked path is a gate input the lane must run for.
224
+ expect(skipped.filter((filePath) => !filePath.endsWith(".md"))).toEqual([])
225
+ expect(runs.filter((filePath) => filePath.endsWith(".md"))).toEqual([])
226
+ })
227
+
228
+ })