|
| 1 | +/* |
| 2 | + * Turns a Windows fatal exit status into something a human can act on, and decides whether it is |
| 3 | + * worth retrying. |
| 4 | + * |
| 5 | + * Issue #47: `pnpm dist:desktop:win:x64` intermittently died with |
| 6 | + * |
| 7 | + * [3] @t3tools/desktop#build: node scripts/build-preview-annotation-css.mjs FAILED (exit code: -1073741502) |
| 8 | + * |
| 9 | + * and an immediate re-run succeeded. `-1073741502` is `0xC0000142`, STATUS_DLL_INIT_FAILED — a |
| 10 | + * Windows *process startup* condition, not an error our code raised. Nothing in that line says so, |
| 11 | + * which sends whoever reads it looking for a bug in a script that is fine. |
| 12 | + * |
| 13 | + * THE FORM MATTERS. vp prints the signed 32-bit decimal, because that is what Node reports for a |
| 14 | + * child's status. The hex spelling appears nowhere in the output. The release workflow's original |
| 15 | + * classifier grepped for `0xC0000142|0xC0000005|STATUS_DLL_INIT_FAILED|Access violation` — none of |
| 16 | + * which the observed log contains — so the retry it was written to trigger could never have fired. |
| 17 | + * That is the bug this file exists to fix, and it is why every spelling is matched here rather |
| 18 | + * than whichever one seemed natural. |
| 19 | + * |
| 20 | + * Retryable and not-retryable are both worth naming. A status that means "the machine was under |
| 21 | + * pressure when this process started" deserves another attempt; one that means "this program |
| 22 | + * corrupted its own heap" does not, and quietly retrying it three times only makes the eventual |
| 23 | + * failure slower and more confusing. |
| 24 | + * |
| 25 | + * `.mjs` for the same reason as its siblings here: the workflow runs it on the runner image's |
| 26 | + * Node, with no `setup-node` step in front of it. |
| 27 | + */ |
| 28 | + |
| 29 | +/** |
| 30 | + * @typedef {object} WindowsStatus |
| 31 | + * @property {string} name NTSTATUS symbol, as documented by Microsoft. |
| 32 | + * @property {number} unsigned The value as an unsigned 32-bit integer. |
| 33 | + * @property {number} signed The same value as Node reports it — signed 32-bit. |
| 34 | + * @property {boolean} transient Whether another attempt is reasonable. |
| 35 | + * @property {string} meaning What actually happened, in a sentence. |
| 36 | + * @property {string} advice What to do about it. |
| 37 | + */ |
| 38 | + |
| 39 | +/** @type {readonly WindowsStatus[]} */ |
| 40 | +export const WINDOWS_FATAL_STATUSES = [ |
| 41 | + { |
| 42 | + name: "STATUS_DLL_INIT_FAILED", |
| 43 | + unsigned: 0xc0000142, |
| 44 | + signed: -1073741502, |
| 45 | + transient: true, |
| 46 | + meaning: |
| 47 | + "A DLL's initialisation routine failed while the process was starting, so the program never reached main().", |
| 48 | + advice: |
| 49 | + "Usually desktop-heap or session resource pressure from spawning several processes at once. Retry, and prefer serialising the build over widening the pool.", |
| 50 | + }, |
| 51 | + { |
| 52 | + name: "STATUS_ACCESS_VIOLATION", |
| 53 | + unsigned: 0xc0000005, |
| 54 | + signed: -1073741819, |
| 55 | + transient: true, |
| 56 | + meaning: "The process read or wrote memory it does not own — a segfault, in Unix terms.", |
| 57 | + advice: |
| 58 | + "The weakest member of this table: it is a genuine crash, and it is only treated as retryable because it also shows up under the same concurrent-spawn pressure as STATUS_DLL_INIT_FAILED. If it recurs on retry, stop treating it as flaky.", |
| 59 | + }, |
| 60 | + { |
| 61 | + name: "STATUS_DLL_NOT_FOUND", |
| 62 | + unsigned: 0xc0000135, |
| 63 | + signed: -1073741515, |
| 64 | + transient: false, |
| 65 | + meaning: "A DLL the program links against is not on the search path.", |
| 66 | + advice: |
| 67 | + "Deterministic, so retrying cannot help. Usually a missing Visual C++ redistributable or a toolchain step that did not run.", |
| 68 | + }, |
| 69 | + { |
| 70 | + name: "STATUS_INVALID_IMAGE_FORMAT", |
| 71 | + unsigned: 0xc000007b, |
| 72 | + signed: -1073741701, |
| 73 | + transient: false, |
| 74 | + meaning: |
| 75 | + "An executable or DLL is the wrong architecture — a 32-bit image loaded into a 64-bit process, or the reverse.", |
| 76 | + advice: "Deterministic. Check which arch the failing dependency was built for.", |
| 77 | + }, |
| 78 | + { |
| 79 | + name: "STATUS_HEAP_CORRUPTION", |
| 80 | + unsigned: 0xc0000374, |
| 81 | + signed: -1073740940, |
| 82 | + transient: false, |
| 83 | + meaning: "The process corrupted its own heap and Windows killed it.", |
| 84 | + advice: |
| 85 | + "A real bug, not resource pressure. Do not retry; capture the failing step and report it.", |
| 86 | + }, |
| 87 | + { |
| 88 | + name: "STATUS_STACK_BUFFER_OVERRUN", |
| 89 | + unsigned: 0xc0000409, |
| 90 | + signed: -1073740791, |
| 91 | + transient: false, |
| 92 | + meaning: |
| 93 | + "A stack buffer was overrun and the security cookie check aborted the process. Also what Windows reports for a fail-fast abort.", |
| 94 | + advice: "A real bug. Do not retry.", |
| 95 | + }, |
| 96 | +]; |
| 97 | + |
| 98 | +/** |
| 99 | + * Looks a status up by any of the spellings that appear in real logs: the signed decimal Node |
| 100 | + * reports, the unsigned decimal, the hex form, or the NTSTATUS name. |
| 101 | + * |
| 102 | + * @param {number | string} code |
| 103 | + * @returns {WindowsStatus | undefined} |
| 104 | + */ |
| 105 | +export function describeWindowsExitCode(code) { |
| 106 | + if (typeof code === "number") { |
| 107 | + return WINDOWS_FATAL_STATUSES.find((s) => s.signed === code || s.unsigned === code); |
| 108 | + } |
| 109 | + const token = String(code).trim(); |
| 110 | + const numeric = /^-?\d+$/u.test(token) |
| 111 | + ? Number(token) |
| 112 | + : /^0x[0-9a-f]+$/iu.test(token) |
| 113 | + ? Number.parseInt(token, 16) |
| 114 | + : undefined; |
| 115 | + if (numeric !== undefined) return describeWindowsExitCode(numeric); |
| 116 | + return WINDOWS_FATAL_STATUSES.find((s) => s.name.toLowerCase() === token.toLowerCase()); |
| 117 | +} |
| 118 | + |
| 119 | +/** |
| 120 | + * Every status named anywhere in a build log, in table order. |
| 121 | + * |
| 122 | + * Matching is deliberately generous — signed decimal, unsigned decimal, hex, and the NTSTATUS |
| 123 | + * name — because which one appears depends on who printed it. vp prints signed decimal; Windows |
| 124 | + * dialogs print hex; a crash dump prints the name. |
| 125 | + * |
| 126 | + * @param {string} logText |
| 127 | + * @returns {readonly WindowsStatus[]} |
| 128 | + */ |
| 129 | +export function findWindowsFatalStatuses(logText) { |
| 130 | + const text = String(logText ?? ""); |
| 131 | + return WINDOWS_FATAL_STATUSES.filter((status) => { |
| 132 | + const hex = status.unsigned.toString(16); |
| 133 | + const patterns = [ |
| 134 | + // `\b` is wrong at both ends here. The leading `-` of the signed form is a non-word |
| 135 | + // character, so `\b-1073741502` never matches after `code: `; and a trailing `\b` would |
| 136 | + // still match inside `-10737415021`. Hence explicit "no digit or minus before, no digit |
| 137 | + // after", which is what stops a build id from being read as a crash. |
| 138 | + new RegExp(`(?<![\\d-])${status.signed}(?!\\d)`, "u"), |
| 139 | + new RegExp(`(?<![\\d-])${status.unsigned}(?!\\d)`, "u"), |
| 140 | + new RegExp(`0x0*${hex}\\b`, "iu"), |
| 141 | + new RegExp(`\\b${status.name}\\b`, "iu"), |
| 142 | + ]; |
| 143 | + return patterns.some((pattern) => pattern.test(text)); |
| 144 | + }); |
| 145 | +} |
| 146 | + |
| 147 | +/** |
| 148 | + * True when every fatal status in the log is one worth retrying, and there is at least one. |
| 149 | + * |
| 150 | + * "Every", not "any": a log carrying both a heap corruption and a DLL-init failure is not a flaky |
| 151 | + * build, and retrying it would hide the corruption behind two more minutes of compute. |
| 152 | + * |
| 153 | + * @param {string} logText |
| 154 | + */ |
| 155 | +export function isTransientProcessStartFailure(logText) { |
| 156 | + const found = findWindowsFatalStatuses(logText); |
| 157 | + return found.length > 0 && found.every((status) => status.transient); |
| 158 | +} |
| 159 | + |
| 160 | +/** |
| 161 | + * The human-readable report. Written for whoever is reading a failed CI run at the point where |
| 162 | + * the only other evidence is a negative integer. |
| 163 | + * |
| 164 | + * @param {string} logText |
| 165 | + */ |
| 166 | +export function explainWindowsFailure(logText) { |
| 167 | + const found = findWindowsFatalStatuses(logText); |
| 168 | + if (found.length === 0) return ""; |
| 169 | + |
| 170 | + const lines = []; |
| 171 | + for (const status of found) { |
| 172 | + lines.push( |
| 173 | + `${status.name} (0x${status.unsigned.toString(16).toUpperCase()}, reported by Node as ${status.signed})`, |
| 174 | + ` What it means: ${status.meaning}`, |
| 175 | + ` ${status.transient ? "Retryable" : "NOT retryable"}: ${status.advice}`, |
| 176 | + ); |
| 177 | + } |
| 178 | + return lines.join("\n"); |
| 179 | +} |
| 180 | + |
| 181 | +// CLI: `node scripts/t3x/windows-exit-codes.mjs --classify <logfile>` |
| 182 | +// |
| 183 | +// Prints the explanation, then exits 0 when a retry is warranted and 1 when it is not — so the |
| 184 | +// caller can write `if node … --classify "$log"; then retry; fi` without parsing anything. |
| 185 | +if ( |
| 186 | + process.argv[1] && |
| 187 | + process.argv[1].endsWith("windows-exit-codes.mjs") && |
| 188 | + process.argv.includes("--classify") |
| 189 | +) { |
| 190 | + const { readFileSync } = await import("node:fs"); |
| 191 | + const file = process.argv[process.argv.indexOf("--classify") + 1]; |
| 192 | + if (!file) { |
| 193 | + console.error("usage: windows-exit-codes.mjs --classify <logfile>"); |
| 194 | + process.exit(2); |
| 195 | + } |
| 196 | + let text = ""; |
| 197 | + try { |
| 198 | + text = readFileSync(file, "utf8"); |
| 199 | + } catch (error) { |
| 200 | + console.error(`Could not read ${file}: ${error instanceof Error ? error.message : error}`); |
| 201 | + process.exit(2); |
| 202 | + } |
| 203 | + const explanation = explainWindowsFailure(text); |
| 204 | + if (explanation) console.error(explanation); |
| 205 | + else console.error("No known Windows fatal status appears in this log."); |
| 206 | + process.exit(isTransientProcessStartFailure(text) ? 0 : 1); |
| 207 | +} |
0 commit comments