@jonmilner/local-ci 0.17.0 → 0.18.0
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/README.md +14 -1
- package/dist/vitest-entry.d.ts +41 -0
- package/dist/vitest-entry.js +87 -0
- package/package.json +5 -1
package/README.md
CHANGED
|
@@ -106,6 +106,19 @@ await withCheckLock("my-repo browser", async () => {
|
|
|
106
106
|
});
|
|
107
107
|
```
|
|
108
108
|
|
|
109
|
-
`withCheckLock(holder, fn, options?)` waits while another holder has the lock, logging `local-ci: waiting for the check lock, held by pid <pid> (<holder>)` to stderr as the CLI does, runs `fn`, and releases the lock when `fn` returns or throws. `holder` is the label other waiters see. `lockCheck(holder, options?)` does the take and returns the release function, for callers that can't wrap their work in a function. `options.file` overrides the lock path and `options.onWait` replaces the wait message. The path is `check.lock` in the state directory above, so no repo config is needed. A call nested under an ancestor process that holds the lock runs without waiting and leaves the lock alone. Pass `options.background: true` for a long job run after a push, such as a browser suite: it still waits for a running check, but `local-ci` checks (and other non-background callers) run beside it instead of waiting, so a push never sits in its hook behind its run. Background jobs queue behind each other in arrival order: each waiter writes a ticket file to `check.lock.queue/` with its pid, arrival time and head start, and takes the lock only when no live ticket sorts before its own. `options.headStartMs` (milliseconds, default 0) moves a background job up by that much: it sorts by arrival minus head start, so it passes jobs that arrived less than that long before it, and no others. A ticket whose process died, that predates the last boot, or that can't be parsed is removed by the next waiter that finds it, so a killed waiter can't wedge the queue. A job held back only by a ticket, with the lock free, says so: `local-ci: waiting for the check lock, held by pid <pid> (queued ahead)`. Checks take no ticket and never wait behind queued background jobs; when the lock is free, whichever polls first takes it. Versions before the queue ignore tickets, so a waiter from such a version (another repo pinned to an older local-ci) can still take the lock out of turn. A check run beside a background job takes `check.lock.beside` instead, so checks still run one at a time: a second check started during the job waits for the first, and whoever takes `check.lock` after the background job ends (another background job or a check) waits for a check still running beside it. A background job waiting that way holds `check.lock` as a check would, without the `background` line, until the beside check ends, so checks arriving meanwhile wait in turn rather than run beside a job that has not started. A check nested in a beside check runs under its lock without waiting. A beside lock whose holder died is taken over, as `check.lock` is. Versions before the beside lock ignore it, so a check from such a version (another repo pinned to an older local-ci) can still run beside a newer beside check. The lock file marks such a lock with a third line, `background`; a file without it (as older versions wrote) is waited on as before. SIGINT, SIGTERM or SIGHUP releases the lock and ends the process, so a job that needs its own signal cleanup should run it before calling the release itself. The package has an `exports` map, so deep imports other than `./lock` no longer resolve.
|
|
109
|
+
`withCheckLock(holder, fn, options?)` waits while another holder has the lock, logging `local-ci: waiting for the check lock, held by pid <pid> (<holder>)` to stderr as the CLI does, runs `fn`, and releases the lock when `fn` returns or throws. `holder` is the label other waiters see. `lockCheck(holder, options?)` does the take and returns the release function, for callers that can't wrap their work in a function. `options.file` overrides the lock path and `options.onWait` replaces the wait message. The path is `check.lock` in the state directory above, so no repo config is needed. A call nested under an ancestor process that holds the lock runs without waiting and leaves the lock alone. Pass `options.background: true` for a long job run after a push, such as a browser suite: it still waits for a running check, but `local-ci` checks (and other non-background callers) run beside it instead of waiting, so a push never sits in its hook behind its run. Background jobs queue behind each other in arrival order: each waiter writes a ticket file to `check.lock.queue/` with its pid, arrival time and head start, and takes the lock only when no live ticket sorts before its own. `options.headStartMs` (milliseconds, default 0) moves a background job up by that much: it sorts by arrival minus head start, so it passes jobs that arrived less than that long before it, and no others. A ticket whose process died, that predates the last boot, or that can't be parsed is removed by the next waiter that finds it, so a killed waiter can't wedge the queue. A job held back only by a ticket, with the lock free, says so: `local-ci: waiting for the check lock, held by pid <pid> (queued ahead)`. Checks take no ticket and never wait behind queued background jobs; when the lock is free, whichever polls first takes it. Versions before the queue ignore tickets, so a waiter from such a version (another repo pinned to an older local-ci) can still take the lock out of turn. A check run beside a background job takes `check.lock.beside` instead, so checks still run one at a time: a second check started during the job waits for the first, and whoever takes `check.lock` after the background job ends (another background job or a check) waits for a check still running beside it. A background job waiting that way holds `check.lock` as a check would, without the `background` line, until the beside check ends, so checks arriving meanwhile wait in turn rather than run beside a job that has not started. A check nested in a beside check runs under its lock without waiting. A beside lock whose holder died is taken over, as `check.lock` is. Versions before the beside lock ignore it, so a check from such a version (another repo pinned to an older local-ci) can still run beside a newer beside check. The lock file marks such a lock with a third line, `background`; a file without it (as older versions wrote) is waited on as before. SIGINT, SIGTERM or SIGHUP releases the lock and ends the process, so a job that needs its own signal cleanup should run it before calling the release itself. The package has an `exports` map, so deep imports other than `./lock` and `./vitest` no longer resolve.
|
|
110
|
+
|
|
111
|
+
### Browser test runs under the check lock
|
|
112
|
+
|
|
113
|
+
`@jonmilner/local-ci/vitest` is a vitest `globalSetup` that makes a run take the check lock as a check when it includes a browser project, so browser runs go one at a time however they start (`npx vitest`, `pnpm test`, an IDE), and queue with `local-ci` checks:
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
import { withBrowserLock } from "@jonmilner/local-ci/vitest";
|
|
117
|
+
import { defineConfig } from "vitest/config";
|
|
118
|
+
|
|
119
|
+
export default defineConfig(withBrowserLock({ test: { projects: [/* unit, storybook, ... */] } }));
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`withBrowserLock(config)` appends the setup to the root `test.globalSetup`, which vitest runs once per run in its main process, before any worker or browser starts; `browserLockSetup` is the setup file's path, for configs that list `globalSetup` themselves. The setup looks at the projects the run selected (after `--project` filters): if any has `browser.enabled`, it takes the lock, waiting as long as it takes and printing `local-ci: waiting for the check lock, held by pid <pid> (<holder>)`, and its teardown releases it when the run ends, pass or fail. A run with only node or jsdom projects never takes it. The holder is `<name> vitest browser`, `<name>` from the nearest `package.json`. A run nested under a holder (`local-ci run -- pnpm test`, a `pnpm check` that local-ci runs) goes ahead without waiting. Projects that each list the setup share one lock, even through separate copies of the module, so a run takes it once. Ctrl-C, SIGTERM or SIGHUP releases it and ends the run; a run killed outright is taken over as a dead holder. Watch mode takes no lock, so a watcher left open never blocks the machine's checks; agents and scripts, with no TTY, get run mode. It needs vitest 3 or later, whose setup sees the run's projects.
|
|
110
123
|
|
|
111
124
|
Part of [jonmilner/config](https://github.com/jonmilner/config#readme).
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import { type LockCheckOptions } from "./check-lock.ts";
|
|
2
|
+
/** The parts of vitest's `TestProject` this reads, so local-ci needs no vitest dependency. */
|
|
3
|
+
export interface BrowserLockProject {
|
|
4
|
+
config: {
|
|
5
|
+
browser?: {
|
|
6
|
+
enabled?: boolean;
|
|
7
|
+
};
|
|
8
|
+
root?: string;
|
|
9
|
+
};
|
|
10
|
+
vitest?: {
|
|
11
|
+
config?: {
|
|
12
|
+
watch?: boolean;
|
|
13
|
+
};
|
|
14
|
+
projects: readonly {
|
|
15
|
+
config: {
|
|
16
|
+
browser?: {
|
|
17
|
+
enabled?: boolean;
|
|
18
|
+
};
|
|
19
|
+
};
|
|
20
|
+
}[];
|
|
21
|
+
};
|
|
22
|
+
}
|
|
23
|
+
/** This file's path, for a config's `test.globalSetup`. */
|
|
24
|
+
export declare const browserLockSetup: string;
|
|
25
|
+
/**
|
|
26
|
+
* Adds the browser lock to a vitest config's root `test.globalSetup`, which vitest runs once per
|
|
27
|
+
* run. `defineConfig(withBrowserLock({ test: { projects: [...] } }))`.
|
|
28
|
+
*/
|
|
29
|
+
export declare function withBrowserLock<T extends {
|
|
30
|
+
test?: {
|
|
31
|
+
globalSetup?: string | string[];
|
|
32
|
+
};
|
|
33
|
+
}>(config: T): T;
|
|
34
|
+
/**
|
|
35
|
+
* Takes the check lock as a check when the run includes a browser project, waiting while another
|
|
36
|
+
* holds it, and returns the teardown that releases it. A run with only node or jsdom projects, or
|
|
37
|
+
* one nested under a lock holder such as `local-ci run`, doesn't wait. Watch mode doesn't take it
|
|
38
|
+
* either, so a watcher left open never blocks the machine's checks. Projects that each list this
|
|
39
|
+
* file share one lock, so the run takes it once; the first call's `options` apply.
|
|
40
|
+
*/
|
|
41
|
+
export default function setup(project: BrowserLockProject, options?: Pick<LockCheckOptions, "file" | "onWait">): Promise<(() => void) | undefined>;
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
// The `@jonmilner/local-ci/vitest` entry: a vitest `globalSetup` that holds the machine-wide check
|
|
2
|
+
// lock for a run that includes a browser project, so browser runs go one at a time however started.
|
|
3
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
4
|
+
import { basename, dirname, join, resolve } from "node:path";
|
|
5
|
+
import { fileURLToPath } from "node:url";
|
|
6
|
+
import { lockCheck } from "./check-lock.js";
|
|
7
|
+
/** This file's path, for a config's `test.globalSetup`. */
|
|
8
|
+
export const browserLockSetup = fileURLToPath(import.meta.url);
|
|
9
|
+
/**
|
|
10
|
+
* Adds the browser lock to a vitest config's root `test.globalSetup`, which vitest runs once per
|
|
11
|
+
* run. `defineConfig(withBrowserLock({ test: { projects: [...] } }))`.
|
|
12
|
+
*/
|
|
13
|
+
export function withBrowserLock(config) {
|
|
14
|
+
const setup = config.test?.globalSetup;
|
|
15
|
+
const files = [setup ?? []].flat();
|
|
16
|
+
if (files.includes(browserLockSetup))
|
|
17
|
+
return config;
|
|
18
|
+
return { ...config, test: { ...config.test, globalSetup: [...files, browserLockSetup] } };
|
|
19
|
+
}
|
|
20
|
+
/** The `name` in the nearest `package.json` at or above `dir`, else the directory's name. */
|
|
21
|
+
function repoName(dir) {
|
|
22
|
+
for (let at = resolve(dir);; at = dirname(at)) {
|
|
23
|
+
const file = join(at, "package.json");
|
|
24
|
+
if (existsSync(file)) {
|
|
25
|
+
try {
|
|
26
|
+
const { name } = JSON.parse(readFileSync(file, "utf8"));
|
|
27
|
+
if (typeof name === "string" && name)
|
|
28
|
+
return name;
|
|
29
|
+
}
|
|
30
|
+
catch {
|
|
31
|
+
// An unreadable package.json names nothing; keep looking above it.
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
if (dirname(at) === at)
|
|
35
|
+
return basename(resolve(dir)) || "unknown";
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
/** Whether the run selected a project with the browser enabled, `--project` filters applied. */
|
|
39
|
+
function runsBrowser(project) {
|
|
40
|
+
const projects = [project, ...(project.vitest?.projects ?? [])];
|
|
41
|
+
return projects.some((p) => p.config.browser?.enabled === true);
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* The lock this process holds, shared by every project whose globalSetup lists this file. It
|
|
45
|
+
* lives on `globalThis`, so two copies of this module (one per module runner, a linked package)
|
|
46
|
+
* share it too: a second `lockCheck` in the same process would wait on its own pid forever.
|
|
47
|
+
*/
|
|
48
|
+
const SHARED = Symbol.for("@jonmilner/local-ci/vitest lock");
|
|
49
|
+
const slot = globalThis;
|
|
50
|
+
/**
|
|
51
|
+
* Takes the check lock as a check when the run includes a browser project, waiting while another
|
|
52
|
+
* holds it, and returns the teardown that releases it. A run with only node or jsdom projects, or
|
|
53
|
+
* one nested under a lock holder such as `local-ci run`, doesn't wait. Watch mode doesn't take it
|
|
54
|
+
* either, so a watcher left open never blocks the machine's checks. Projects that each list this
|
|
55
|
+
* file share one lock, so the run takes it once; the first call's `options` apply.
|
|
56
|
+
*/
|
|
57
|
+
export default async function setup(project, options = {}) {
|
|
58
|
+
if (project.vitest?.config?.watch || !runsBrowser(project))
|
|
59
|
+
return undefined;
|
|
60
|
+
if (!slot[SHARED]) {
|
|
61
|
+
const holder = `${repoName(project.config.root ?? process.cwd())} vitest browser`;
|
|
62
|
+
slot[SHARED] = { release: lockCheck(holder, options), users: 0 };
|
|
63
|
+
}
|
|
64
|
+
const lock = slot[SHARED];
|
|
65
|
+
lock.users += 1;
|
|
66
|
+
let release;
|
|
67
|
+
try {
|
|
68
|
+
release = await lock.release;
|
|
69
|
+
}
|
|
70
|
+
catch (error) {
|
|
71
|
+
if (slot[SHARED] === lock)
|
|
72
|
+
delete slot[SHARED];
|
|
73
|
+
throw error;
|
|
74
|
+
}
|
|
75
|
+
let done = false;
|
|
76
|
+
return () => {
|
|
77
|
+
if (done)
|
|
78
|
+
return;
|
|
79
|
+
done = true;
|
|
80
|
+
lock.users -= 1;
|
|
81
|
+
if (lock.users > 0)
|
|
82
|
+
return;
|
|
83
|
+
if (slot[SHARED] === lock)
|
|
84
|
+
delete slot[SHARED];
|
|
85
|
+
release();
|
|
86
|
+
};
|
|
87
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jonmilner/local-ci",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.18.0",
|
|
4
4
|
"description": "Run a repo's check in a pre-push hook and post the result as GitHub commit statuses",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -22,6 +22,10 @@
|
|
|
22
22
|
"types": "./dist/lock-entry.d.ts",
|
|
23
23
|
"default": "./dist/lock-entry.js"
|
|
24
24
|
},
|
|
25
|
+
"./vitest": {
|
|
26
|
+
"types": "./dist/vitest-entry.d.ts",
|
|
27
|
+
"default": "./dist/vitest-entry.js"
|
|
28
|
+
},
|
|
25
29
|
"./package.json": "./package.json"
|
|
26
30
|
},
|
|
27
31
|
"publishConfig": {
|