@jonmilner/local-ci 0.14.1 → 0.15.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 CHANGED
@@ -72,7 +72,9 @@ Host github.com
72
72
 
73
73
  Logs, the record of passed commits and the release lock live in `~/.local/state/local-ci/<repo>.log`, `<repo>.passed` and `<repo>.release.lock` (`$XDG_STATE_HOME` if set). A lock whose process has died is taken over.
74
74
 
75
- One check command runs at a time on the machine, across every repo, so overlapping checks can't starve each other's tests: `pre-push`, `status`, the `status` runs `renovate` starts, and `local-ci run` each take `check.lock` in the same directory around the command they run (not the status posts). Nothing else takes it: a bare `pnpm check` or `pnpm test` runs beside every other check, so start a full check by hand with `local-ci run -- pnpm check`. The lock only runs checks one at a time; it does not wait for memory pressure or swap to clear. A run that finds it held prints `local-ci: waiting for the check lock, held by pid <pid> (<repo> <short-sha>)` (`<repo> <command>` for `local-ci run`, with the command cut to 60 characters), again whenever another run takes it first, and polls every second until the holder exits or dies; Ctrl-C stops the wait. Checks don't queue, so the next one to poll after a release goes first; background jobs wait in arrival order (see [below](#taking-the-check-lock-from-your-own-scripts)). After the wait it skips a commit that passed meanwhile and re-applies the clean-tree rule. The lock goes when the check passes, fails or is killed by a signal. Ctrl-C, SIGTERM, SIGHUP or SIGQUIT (Ctrl-\\) to local-ci passes the signal to the check's whole process group (so a check script's children get it too), waits for the check to exit, then releases the lock and dies of the signal, so a check never outlives its lock. A lock whose holder died (SIGKILL, a crash) or that predates the last boot is taken over by the next run. A local-ci check nested inside a check (one that pushes, say) sees its ancestor holds the lock and runs without waiting. A check that finds a background job's lock (see below) runs beside the job instead of waiting and leaves that lock alone, printing `local-ci: running beside background job pid <pid> (<holder>), without the check lock`; it holds `check.lock.beside` meanwhile, so another check waits for it rather than overlapping, and signals still stop it and release that lock as above. Each check run appends its duration and outcome to the log when it ends, e.g. `[<end time>] abc1234: pnpm check passed in 71.2s` (or `failed in`, or `did not finish after` when the check is killed by a signal or can't start); a commit that already passed is skipped and logs nothing. Ctrl-C stops the check, which logs `did not finish after`.
75
+ A pass is recorded by commit and by tree: `<repo>.passed` gets a `<sha>\t<command>` line and a `tree:<tree>\t<command as JSON>` line (`git rev-parse <sha>^{tree}`; JSON keeps a command over several lines on one line). A commit that has not passed but whose tree passed under the same check command (a squash or merge commit with the PR head's files, or a reworded commit) counts as passed without running the check: `pre-push` and `status` skip it, record a pass for its sha, and print and log `<short-sha>: <command> already passed on tree <short-tree>; reused without running`. A different tree or command runs the check. Unlike a commit record, a tree record counts only for a clean `HEAD`, so the command it matches is the one that commit's `package.json` names. It assumes the check reads only the commit's files: a check that reads the commit message or history (a commitlint of `HEAD`, a diff from a merge base) can pass on one commit and fail on another with the same tree, and its result is reused anyway. Records written before tree lines existed still match their sha, but no tree.
76
+
77
+ One check command runs at a time on the machine, across every repo, so overlapping checks can't starve each other's tests: `pre-push`, `status`, the `status` runs `renovate` starts, and `local-ci run` each take `check.lock` in the same directory around the command they run (not the status posts). Nothing else takes it: a bare `pnpm check` or `pnpm test` runs beside every other check, so start a full check by hand with `local-ci run -- pnpm check`. The lock only runs checks one at a time; it does not wait for memory pressure or swap to clear. A run that finds it held prints `local-ci: waiting for the check lock, held by pid <pid> (<repo> <short-sha>)` (`<repo> <command>` for `local-ci run`, with the command cut to 60 characters), again whenever another run takes it first, and polls every second until the holder exits or dies; Ctrl-C stops the wait. Checks don't queue, so the next one to poll after a release goes first; background jobs wait in arrival order (see [below](#taking-the-check-lock-from-your-own-scripts)). After the wait it skips a commit that passed meanwhile and re-applies the clean-tree rule. The lock goes when the check passes, fails or is killed by a signal. Ctrl-C, SIGTERM, SIGHUP or SIGQUIT (Ctrl-\\) to local-ci passes the signal to the check's whole process group (so a check script's children get it too), waits for the check to exit, then releases the lock and dies of the signal, so a check never outlives its lock. A lock whose holder died (SIGKILL, a crash) or that predates the last boot is taken over by the next run. A local-ci check nested inside a check (one that pushes, say) sees its ancestor holds the lock and runs without waiting. A check that finds a background job's lock (see below) runs beside the job instead of waiting and leaves that lock alone, printing `local-ci: running beside background job pid <pid> (<holder>), without the check lock`; it holds `check.lock.beside` meanwhile, so another check waits for it rather than overlapping, and signals still stop it and release that lock as above. Each check run appends its duration and outcome to the log when it ends, e.g. `[<end time>] abc1234: pnpm check passed in 71.2s` (or `failed in`, or `did not finish after` when the check is killed by a signal or can't start); a commit that already passed is skipped and logs nothing (one that reuses a pass on its tree logs that instead, see above). Ctrl-C stops the check, which logs `did not finish after`.
76
78
 
77
79
  ### Taking the check lock from your own scripts
78
80
 
package/dist/cli.js CHANGED
@@ -6,7 +6,7 @@ import { basename, dirname, join, relative, resolve } from "node:path";
6
6
  import { fileURLToPath } from "node:url";
7
7
  import { heldCheckLock, lockCheck, withCheckLock } from "./check-lock.js";
8
8
  import { commitMsg } from "./commit-msg.js";
9
- import { appendLog, checkRunMessage, logLine, passedCommand, recordPass, releaseEnabled, resolveCommand, shimCommand, statePaths, } from "./config.js";
9
+ import { appendLog, checkRunMessage, logLine, passedCommand, recordPass, releaseEnabled, resolveCommand, shimCommand, statePaths, treePassed, treeReuseMessage, } from "./config.js";
10
10
  import { exec, run } from "./exec.js";
11
11
  import { assertGhAuth, checkStatus, postStatus, prTitleStatus, viewPr, waitForCommit, waitForOpenPr, } from "./github.js";
12
12
  import { hooksDir, installHooks, missingHooks } from "./hooks.js";
@@ -81,19 +81,50 @@ async function assertCheckable(sha) {
81
81
  async function runCheck(current, sha) {
82
82
  if (passedCommand(current.passed, sha))
83
83
  return;
84
+ // A tree reuse waits for the clean-tree rule too, so the command it matches is the one `sha`'s
85
+ // own package.json names.
84
86
  await assertCheckable(sha);
87
+ const tree = await git("rev-parse", `${sha}^{tree}`);
88
+ if (reuseTreePass(current, sha, tree))
89
+ return;
85
90
  const unlock = await lockCheck(`${current.name} ${sha.slice(0, 7)}`, { file: current.checkLock });
86
91
  try {
87
- // Another run may have passed it, or the tree changed, while this one waited.
92
+ // Another run may have passed it, or the working tree changed, while this one waited.
88
93
  if (passedCommand(current.passed, sha))
89
94
  return;
90
95
  await assertCheckable(sha);
91
- await runLocked(current, sha);
96
+ if (reuseTreePass(current, sha, tree))
97
+ return;
98
+ await runLocked(current, sha, tree);
92
99
  }
93
100
  finally {
94
101
  unlock();
95
102
  }
96
103
  }
104
+ /**
105
+ * When the check command already passed on another commit with the same `tree` (a merge commit
106
+ * with the PR head's files, say), records a pass for `sha`, so `post` finds it, logs the reuse and
107
+ * returns true.
108
+ */
109
+ function reuseTreePass({ root, passed, log: logFile }, sha, tree) {
110
+ const command = resolveCommand(root);
111
+ if (!treePassed(passed, tree, command))
112
+ return false;
113
+ recordPass(passed, sha, command);
114
+ const message = treeReuseMessage(sha, command, tree);
115
+ err(`local-ci: ${message}`);
116
+ logQuietly(logFile, message);
117
+ return true;
118
+ }
119
+ /** Appends to the repo's log; a log that can't be written must not change the check's outcome. */
120
+ function logQuietly(file, message) {
121
+ try {
122
+ appendLog(file, message);
123
+ }
124
+ catch (error) {
125
+ err(`local-ci: could not log "${message}": ${error instanceof Error ? error.message : String(error)}`);
126
+ }
127
+ }
97
128
  /** Runs a program under the check lock, attached to it so a signal to local-ci reaches it. */
98
129
  async function runHeld(file, args, cwd) {
99
130
  const held = heldCheckLock();
@@ -115,7 +146,7 @@ async function runHeld(file, args, cwd) {
115
146
  return { ...result, interrupted: held?.signal };
116
147
  }
117
148
  /** Runs the check command under the check lock, logging its duration and recording a pass. */
118
- async function runLocked({ root, passed, log: logFile }, sha) {
149
+ async function runLocked({ root, passed, log: logFile }, sha, tree) {
119
150
  const command = resolveCommand(root);
120
151
  err(`local-ci: running ${command} on ${sha.slice(0, 7)}`);
121
152
  const started = performance.now();
@@ -124,13 +155,7 @@ async function runLocked({ root, passed, log: logFile }, sha) {
124
155
  const { interrupted } = result;
125
156
  const status = interrupted ? null : result.status;
126
157
  // Every run's duration goes in the log, so a faster check can be measured against a slower one.
127
- // A log that can't be written must not change the check's outcome.
128
- try {
129
- appendLog(logFile, checkRunMessage(sha, command, status, performance.now() - started));
130
- }
131
- catch (error) {
132
- err(`local-ci: could not log the run: ${error instanceof Error ? error.message : String(error)}`);
133
- }
158
+ logQuietly(logFile, checkRunMessage(sha, command, status, performance.now() - started));
134
159
  // A spawn error or a signal means the check never finished, so it is not a failure to post.
135
160
  if (status === null) {
136
161
  const cause = interrupted ?? result.error ?? result.signal;
@@ -138,7 +163,7 @@ async function runLocked({ root, passed, log: logFile }, sha) {
138
163
  }
139
164
  if (status !== 0)
140
165
  throw new CheckFailed(command, sha);
141
- recordPass(passed, sha, command);
166
+ recordPass(passed, sha, command, tree);
142
167
  }
143
168
  /**
144
169
  * Runs `-- <command>` under the check lock, so a full check started by hand waits its turn with
package/dist/config.d.ts CHANGED
@@ -28,7 +28,15 @@ export declare function appendLog(file: string, message: string, now?: Date): vo
28
28
  * A null `status` (a spawn error or a signal) means the check never finished.
29
29
  */
30
30
  export declare function checkRunMessage(sha: string, command: string, status: number | null, ms: number): string;
31
- /** Records that `command` passed at `sha`, one `<sha>\t<command>` line per commit. */
32
- export declare function recordPass(file: string, sha: string, command: string): void;
31
+ /**
32
+ * Records that `command` passed at `sha`, one `<sha>\t<command>` line per commit, plus a
33
+ * `tree:<tree>\t<json command>` line when the commit's tree is given, so another commit with the
34
+ * same files can reuse the pass. JSON keeps a command written over several lines on one line.
35
+ */
36
+ export declare function recordPass(file: string, sha: string, command: string, tree?: string): void;
33
37
  /** The command that last passed at `sha`, or undefined if it was never checked. */
34
38
  export declare function passedCommand(file: string, sha: string): string | undefined;
39
+ /** Whether `command` passed on a commit whose tree is `tree`. Sha-only records never match. */
40
+ export declare function treePassed(file: string, tree: string, command: string): boolean;
41
+ /** The log line for a commit that reused a pass on the same tree instead of running the check. */
42
+ export declare function treeReuseMessage(sha: string, command: string, tree: string): string;
package/dist/config.js CHANGED
@@ -65,12 +65,23 @@ export function checkRunMessage(sha, command, status, ms) {
65
65
  const outcome = status === null
66
66
  ? `did not finish after ${seconds}`
67
67
  : `${status === 0 ? "passed" : "failed"} in ${seconds}`;
68
- // One line per run, even for a command written over several lines.
68
+ return runMessage(sha, command, outcome);
69
+ }
70
+ /** `<short-sha>: <command> <outcome>`, one line per run even for a command over several lines. */
71
+ function runMessage(sha, command, outcome) {
69
72
  return `${sha.slice(0, 7)}: ${command.replace(/\s+/g, " ")} ${outcome}`;
70
73
  }
71
- /** Records that `command` passed at `sha`, one `<sha>\t<command>` line per commit. */
72
- export function recordPass(file, sha, command) {
74
+ /** Starts a pass record's tree line; it never matches a sha, so older readers skip the line. */
75
+ const TREE_PREFIX = "tree:";
76
+ /**
77
+ * Records that `command` passed at `sha`, one `<sha>\t<command>` line per commit, plus a
78
+ * `tree:<tree>\t<json command>` line when the commit's tree is given, so another commit with the
79
+ * same files can reuse the pass. JSON keeps a command written over several lines on one line.
80
+ */
81
+ export function recordPass(file, sha, command, tree) {
73
82
  appendFileSync(file, `${sha}\t${command}\n`);
83
+ if (tree)
84
+ appendFileSync(file, `${treeLine(tree, command)}\n`);
74
85
  }
75
86
  /** The command that last passed at `sha`, or undefined if it was never checked. */
76
87
  export function passedCommand(file, sha) {
@@ -84,3 +95,16 @@ export function passedCommand(file, sha) {
84
95
  }
85
96
  return command;
86
97
  }
98
+ /** Whether `command` passed on a commit whose tree is `tree`. Sha-only records never match. */
99
+ export function treePassed(file, tree, command) {
100
+ if (!existsSync(file))
101
+ return false;
102
+ return readFileSync(file, "utf8").split("\n").includes(treeLine(tree, command));
103
+ }
104
+ function treeLine(tree, command) {
105
+ return `${TREE_PREFIX}${tree}\t${JSON.stringify(command)}`;
106
+ }
107
+ /** The log line for a commit that reused a pass on the same tree instead of running the check. */
108
+ export function treeReuseMessage(sha, command, tree) {
109
+ return runMessage(sha, command, `already passed on tree ${tree.slice(0, 7)}; reused without running`);
110
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jonmilner/local-ci",
3
- "version": "0.14.1",
3
+ "version": "0.15.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": {