chore(release): v5.26.0

Tightens the GitHub fallback work from 5.25.x and rolls in supporting tooling. Highlights:

* `getLatestRelease`, `getReleaseAssetUrl`: silent transparent GraphQL fallback when REST returns 200 + empty body. The `logger.warn` /  `logger.info` chatter is gone — the helpers are silent by design now (errors throw, success returns).
* New `nothrow` option on both helpers, mirroring the `whichSync({ nothrow })` convention from `@socketsecurity/lib/bin`. When true, returns `undefined` instead of throwing on the both-backends-degraded shape.
* Return-type cleanup: `null` → `undefined` everywhere we own the surface. Wire-shape types (REST/GraphQL JSON literals) keep `null` because that's what GitHub puts on the wire.
* Error messages tightened to the CLAUDE.md library-API style: terse, stable, callable-by-`instanceof`/`.message`. The verbose explanations live in the JSDoc.
* `tools/prim` audit gained a `redeclaration` finding kind. It now flags top-level `const ErrorCtor = Error` / `const JSONParse = JSON.parse` / `const ArrayIsArray = Array.isArray` and recommends importing from `./primordials` instead of redeclaring locally. `--coverage` includes redeclarations alongside covered call sites; `--gaps` excludes them. The audit found 14 pre-existing redeclarations in the package (out of scope for this release).
* socket-lib's own github.ts and releases/github.ts now import from `./primordials` instead of redeclaring locally — matches what the new audit recommends.

Tests: 154/154 pass across `github.test.mts` (97) and `releases-github.test.mts` (57). Coverage on `src/github.ts` is 19/19 functions, 80/96 branches, 126/135 statements. `src/releases/github.ts` is 27/29 functions, 105/172 branches (the missing branches are all in pre-existing `downloadAndExtractArchive` / `downloadAndExtractZip` not touched in this release).

Author: jdalton

.git-hooks/pre-commit.mts

@@ -159,7 +159,12 @@ const main = (): number => {
     if (
       file.includes('node_modules/') ||
       file.endsWith('pnpm-lock.yaml') ||
-      file.includes('.git-hooks/')
+      file.includes('.git-hooks/') ||
+      // CHANGELOG entries discuss npx ecosystem *behavior* (cache
+      // semantics, naming conventions) as historical documentation —
+      // they're not commands. Skip the npx/dlx scan for changelogs.
+      file === 'CHANGELOG.md' ||
+      file.endsWith('/CHANGELOG.md')
     ) {
       continue
     }

CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.26.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.26.0) - 2026-04-27
+
+### Added
+
+- `@socketsecurity/lib/github` `GitHubEmptyBodyError` — new exported error class. Thrown by `fetchGitHub` when GitHub returns HTTP 200 OK with a zero-byte body (the documented signature of GitHub Elasticsearch / search-degraded incidents — see https://www.githubstatus.com). Lets callers `instanceof` this error to detect the upstream-degraded shape and route around it instead of catching a confusing downstream `JSON.parse('')` SyntaxError
+- `@socketsecurity/lib/github` `getLatestRelease({ nothrow })` and `@socketsecurity/lib/releases/github` `getReleaseAssetUrl({ nothrow })` — when `true`, return `undefined` instead of throwing if both REST and GraphQL backends are degraded. Matches the existing `nothrow` convention from `@socketsecurity/lib/bin` (`whichSync({ nothrow })`)
+
+### Changed
+
+- `getLatestRelease`, `getReleaseAssetUrl`, `fetchRefShaViaGraphQL` (internal), `fetchReleaseAssetsViaGraphQL` (internal) — return `undefined` (was: `null`) when no result is found. Matches the `__proto__: null` only / `undefined` convention used elsewhere in the package. Callers using `=== null` will need to switch to `=== undefined` or a falsy check; callers using `if (!result)` are unaffected
+- `fetchGhsaDetails` GraphQL fallback path normalizes severity to lowercase (`"MODERATE"` → `"moderate"`) to match the REST endpoint's wire shape. Callers comparing against a single canonical case no longer have to handle both
+- `getLatestRelease` and `getReleaseAssetUrl` no longer log to `logger.info` / `logger.warn` on success, retry, or fallback. The helpers are silent by design now: errors throw, success returns. The `quiet` option is still accepted for backward compat but ignored
+
+### Fixed
+
+- `@socketsecurity/lib/releases/github` `getLatestRelease` now transparently falls back to GraphQL `repository.releases` when the REST `/repos/:owner/:repo/releases` listing endpoint returns HTTP 200 with an empty body. The REST listing shares an Elasticsearch-backed index with search; during incidents the endpoint returns success-with-no-body for arbitrary repos. GraphQL hits a different backend and stays consistent through these outages
+- `@socketsecurity/lib/releases/github` `getReleaseAssetUrl` now transparently falls back to GraphQL `repository.release(tagName).releaseAssets` on the same incident shape. GraphQL's `downloadUrl` field is normalized back to REST's `browser_download_url` so the asset matcher runs unchanged
+- `@socketsecurity/lib/github` `resolveRefToSha` now transparently falls back to GraphQL `repository.ref(qualifiedName)` + `repository.object(oid)` after the REST tag → branch → commit cascade hits the empty-body shape. GraphQL resolves all three forms in one round trip, including dereferencing annotated tags via `Tag.target.oid`
+- `@socketsecurity/lib/github` `fetchGhsaDetails` now falls back to GraphQL `securityAdvisory(ghsaId)` on the empty-body shape. Two field-shape diffs are normalized: severity case (uppercase → lowercase) and `aliases` (derived from GraphQL `identifiers` by filtering out the advisory's own GHSA id)
+- All four fallback paths only fire on `GitHubEmptyBodyError` (the documented incident signature). Real 404s, rate-limit errors, and 5xx responses still propagate as-is — the fallback is reserved for the case REST gives no usable signal
+
+### Tooling
+
+- `tools/prim` audit now detects local-alias redeclarations of primordials (`const ErrorCtor = Error`, `const JSONParse = JSON.parse`, `const ArrayIsArray = Array.isArray`, etc.) at top-level scope and reports them as a new `redeclaration` finding kind. The recommendation is to import the alias from `./primordials` instead of redeclaring it locally. `--coverage` includes redeclarations alongside covered call sites since both are migration candidates against the existing surface; `--gaps` excludes them
+
 ## [5.25.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.25.1) - 2026-04-27
 
 ### Fixed

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "5.25.2",
+  "version": "5.26.0",
   "packageManager": "pnpm@11.0.0-rc.5",
   "license": "MIT",
   "description": "Core utilities and infrastructure for Socket.dev security tools",

src/github.ts

@@ -28,16 +28,12 @@ import { getGhToken, getGithubToken } from './env/github'
 import { getSocketCliGithubToken } from './env/socket-cli'
 import { errorMessage } from './errors'
 import { httpRequest } from './http-request'
+import { ErrorCtor, JSONParse, JSONStringify } from './primordials'
 import { spawn } from './spawn'
 
 import type { TtlCache } from './cache-with-ttl'
 import type { SpawnOptions } from './spawn'
 
-// Pin global primordials at module load. Matches src/packages/provenance.ts.
-const ErrorCtor = Error
-const JSONParse = JSON.parse
-const JSONStringify = JSON.stringify
-
 // GitHub API base URL constant (inlined for coverage mode compatibility).
 const GITHUB_API_BASE_URL = 'https://api.github.com'
 
@@ -83,12 +79,11 @@ export class GitHubEmptyBodyError extends Error {
   /** HTTP status (always 200 — that's what makes this case insidious). */
   status: number
   constructor(url: string) {
-    super(
-      `GitHub API returned HTTP 200 with an empty body for ${url}. ` +
-        'This is the documented signature of an upstream incident — ' +
-        'see https://www.githubstatus.com. Retrying or falling back ' +
-        'to a different transport is recommended.',
-    )
+    // Library-API error: terse and stable so callers can switch on
+    // .name / instanceof without parsing the message. The verbose
+    // background ("documented incident shape", status URL) lives in
+    // the JSDoc above the class declaration.
+    super(`GitHub API returned HTTP 200 with empty body: ${url}`)
     this.name = 'GitHubEmptyBodyError'
     this.status = 200
   }
@@ -390,28 +385,36 @@ async function fetchRefSha(
         // "ref not found" outcome.
         //
         // If GraphQL ALSO fails (network error, GraphQL errors[],
-        // etc.) we silently swallow it and re-throw the *original*
-        // REST error. The reasoning is: the REST cascade error
-        // gives the user an actionable message ("ref not found"),
-        // while a GraphQL transport error is incident plumbing
-        // they can't act on. Better to show the lower-level "we
-        // couldn't find it" error than a confusing GraphQL
-        // exception caused by the same incident.
+        // etc.) we throw an informative "both transports failed"
+        // error so the operator sees the cross-backend signal
+        // rather than a bare last-tier REST error.
         // -----------------------------------------------------------
         if (sawEmptyBody) {
+          let graphqlSha: string | undefined
+          let graphqlErr: unknown
           try {
-            const sha = await fetchRefShaViaGraphQL(
+            graphqlSha = await fetchRefShaViaGraphQL(
               owner,
               repo,
               ref,
               fetchOptions,
             )
-            if (sha) {
-              return sha
-            }
-          } catch {
-            // fall through to the original error
+          } catch (cause) {
+            graphqlErr = cause
+          }
+          if (graphqlSha) {
+            return graphqlSha
+          }
+          if (graphqlErr !== undefined) {
+            throw new ErrorCtor(
+              `Failed to resolve ref "${ref}" for ${owner}/${repo}: both REST and GraphQL backends degraded`,
+              { cause: graphqlErr },
+            )
           }
+          // GraphQL completed successfully but found no match — the ref
+          // genuinely doesn't exist (or the empty-body signal happened
+          // but GitHub has since recovered enough for GraphQL to confirm
+          // the absence). Surface the cleaner "ref not found" message.
         }
         throw new ErrorCtor(
           `failed to resolve ref "${ref}" for ${owner}/${repo}: ${errorMessage(e3)}`,
@@ -451,10 +454,10 @@ async function fetchRefSha(
  *
  * Return contract:
  *   - Returns the SHA string when any form matches.
- *   - Returns `null` when the ref genuinely doesn't exist as a
- *     tag, branch, OR commit. The caller treats `null` the same
+ *   - Returns `undefined` when the ref genuinely doesn't exist as a
+ *     tag, branch, OR commit. The caller treats `undefined` the same
  *     as "REST cascade also failed" — a real "ref not found".
- *   - Returns `null` (not throws) on transport-level failures too:
+ *   - Returns `undefined` (not throws) on transport-level failures too:
  *     non-OK HTTP, empty GraphQL body, or JSON parse error. The
  *     REST cascade's "ref not found" message is more useful to the
  *     end user than a GraphQL transport error.
@@ -464,7 +467,7 @@ async function fetchRefShaViaGraphQL(
   repo: string,
   ref: string,
   options: GitHubFetchOptions,
-): Promise<string | null> {
+): Promise<string | undefined> {
   const token = options.token || getGitHubToken()
   const headers: Record<string, string> = {
     Accept: 'application/vnd.github.v3+json',
@@ -526,10 +529,10 @@ async function fetchRefShaViaGraphQL(
   if (!response.ok || response.body.byteLength === 0) {
     // Either GraphQL itself failed (non-OK status) or it ALSO
     // returned an empty body — both backends are degraded. Return
-    // null so the caller surfaces the original REST error rather
+    // undefined so the caller surfaces the original REST error rather
     // than re-throwing here. We deliberately don't recurse to
     // another transport because there isn't a third option.
-    return null
+    return undefined
   }
   let parsed: {
     data?: {
@@ -549,7 +552,7 @@ async function fetchRefShaViaGraphQL(
   try {
     parsed = JSONParse(response.body.toString('utf8'))
   } catch {
-    return null
+    return undefined
   }
   // GraphQL has two ways of saying "no":
   //
@@ -570,15 +573,15 @@ async function fetchRefShaViaGraphQL(
   // identical to REST when both backends return data.
   const repoData = parsed.data?.repository
   if (!repoData) {
-    return null
+    return undefined
   }
   const tagTarget = repoData.tagRef?.target
   if (tagTarget) {
     if (tagTarget.__typename === 'Tag') {
-      return tagTarget.target?.oid ?? null
+      return tagTarget.target?.oid ?? undefined
     }
     if (tagTarget.__typename === 'Commit') {
-      return tagTarget.oid ?? null
+      return tagTarget.oid ?? undefined
     }
   }
   const branchOid = repoData.branchRef?.target?.oid
@@ -588,7 +591,7 @@ async function fetchRefShaViaGraphQL(
   if (repoData.commit?.__typename === 'Commit' && repoData.commit.oid) {
     return repoData.commit.oid
   }
-  return null
+  return undefined
 }
 
 /**
@@ -781,7 +784,14 @@ export async function fetchGhsaDetails(
     // shape so callers don't see the difference.
     // -------------------------------------------------------------
     if (e instanceof GitHubEmptyBodyError) {
-      return await fetchGhsaDetailsViaGraphQL(ghsaId, options)
+      try {
+        return await fetchGhsaDetailsViaGraphQL(ghsaId, options)
+      } catch (cause) {
+        throw new ErrorCtor(
+          `Failed to fetch advisory ${ghsaId}: both REST and GraphQL backends degraded`,
+          { cause },
+        )
+      }
     }
     throw e
   }