From 8414685ad9bef67ea357958ad2ce2989ebfe2583 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Thu, 3 Sep 2026 23:47:05 -0400 Subject: [PATCH] docs(scripts): correct the release-lookup contract left stale by round 4 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses Copilot review round 5 on #2239. Round 4 made every non-zero release-list response fatal and deleted `isMissingRelease`, but `latestReleaseTag`'s JSDoc still promised `@throws when the lookup fails for any reason other than a 404` — the exact behavior that change removed. The PR description carried the same stale claim. A contract that documents the opposite of the code is worse than none: the next reader reasonably trusts it, and here it would tell them a missing action repo is silently tolerated when it now fails the sweep. The contract now reserves `null` for a successful response carrying no usable release — an action that has never cut one, or whose tags are all unparseable — and states that a failed lookup is never `null`. Documentation only; no behavior change, and the 29 tests are untouched. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01NGtzPg3UxMLszysQXXfqax Signed-off-by: cliffhall --- scripts/dependency-refresh.mjs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/scripts/dependency-refresh.mjs b/scripts/dependency-refresh.mjs index ab54ec1c..e0474f15 100644 --- a/scripts/dependency-refresh.mjs +++ b/scripts/dependency-refresh.mjs @@ -297,7 +297,7 @@ function comparePadded(a, b) { } /** - * The action's highest released version tag, or `null` when it has none. + * The action's highest released version tag. * * Reads the release *list* rather than `releases/latest`, for the reason on * `highestVersionTag`. Drafts and prereleases are excluded — neither is @@ -305,7 +305,10 @@ function comparePadded(a, b) { * rather than paginating every release an action has ever cut: the list comes * back newest-first, so the greatest version is within it for any real action. * - * @throws when the lookup fails for any reason other than a 404 + * @returns {string | null} `null` ONLY for a successful response carrying no + * usable release — an action that has never cut one, or whose tags are all + * unparseable. A failed lookup is never `null`; see below. + * @throws on any non-zero status, 404 included */ function latestReleaseTag(action, spawn) { // `owner/repo/subpath@ref` is a valid `uses:`; releases live on `owner/repo`.