refactor(github): tighten error messages + remove quiet option

Two cleanups on top of the v5.26.0 work:

* `quiet` option removed from `getLatestRelease` and `getReleaseAssetUrl` type signatures. The helpers are silent by design now (errors throw, success returns); there's nothing for `quiet` to suppress. Per the repo's "no backward compat" policy, the option is deleted rather than accepted-but-ignored. Internal callers (`socket-btm.ts`, `downloadGitHubRelease`, `downloadReleaseAsset`) updated to drop the now-unused option arg. CHANGELOG entry moved to `### Removed`.

* All error messages I touched in this release reviewed against the CLAUDE.md "Errors are a UX surface" guidance. Library-API throws should be terse, stable, and include where (owner/repo). Fixes:
  - lowercase `failed to resolve ref` -> capitalized to match siblings
  - `Failed to fetch releases:` -> `Failed to fetch ${owner}/${repo} releases:`
  - `Failed to parse GitHub releases response from <hardcoded URL>` -> `Failed to parse ${owner}/${repo} releases response`
  - `GraphQL error: <messages>` -> `GraphQL securityAdvisory(...) returned errors: <messages>` / `GraphQL repository.releases(...) returned errors: ...` / `GraphQL repository.release(...) returned errors: ...` (which query failed is now visible)
  - `GHSA X not found via GraphQL` -> `GHSA X not found` (transport detail leaked; users don't care which transport)
  - `GraphQL fallback for X failed: ...` -> `Failed to fetch ${owner}/${repo} release X (GraphQL): ...`
  - `Release X not found in Y: GraphQL fallback found no release with that tag` -> `Release X not found in Y` (redundant tail removed)
  - `Failed to parse GitHub release response for tag X` -> `Failed to parse ${owner}/${repo} release X response`
  - `Failed to fetch release X: 503` -> `Failed to fetch ${owner}/${repo} release X: 503`
  - `Release X has no assets` -> `Release X has no assets in ${owner}/${repo}`
  - `Failed to parse GitHub GraphQL release response for X` -> `Failed to parse ${owner}/${repo} release X response (GraphQL)`

Test assertions updated to the new wording. 154/154 still pass. tsgo + lint clean.

Author: jdalton

CHANGELOG.md

@@ -16,7 +16,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `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
+- `getLatestRelease` and `getReleaseAssetUrl` are silent by design now: errors throw, success returns. No more `logger.info` / `logger.warn` calls on success, retry, or fallback
+
+### Removed
+
+- `getLatestRelease({ quiet })` and `getReleaseAssetUrl({ quiet })` — the `quiet` option is gone from the type signatures. Passing it is now a TypeScript error. There's nothing left to suppress (the helpers don't log anymore — see "Changed"). Callers that were passing `{ quiet: true }` as their only option should drop the options arg entirely
 
 ### Fixed
 

src/github.ts

@@ -417,7 +417,7 @@ async function fetchRefSha(
           // the absence). Surface the cleaner "ref not found" message.
         }
         throw new ErrorCtor(
-          `failed to resolve ref "${ref}" for ${owner}/${repo}: ${errorMessage(e3)}`,
+          `Failed to resolve ref "${ref}" for ${owner}/${repo}: ${errorMessage(e3)}`,
         )
       }
     }
@@ -923,12 +923,12 @@ async function fetchGhsaDetailsViaGraphQL(
   }
   if (parsed.errors?.length) {
     throw new ErrorCtor(
-      `GraphQL error: ${parsed.errors.map(e => e.message).join('; ')}`,
+      `GraphQL securityAdvisory(${ghsaId}) returned errors: ${parsed.errors.map(e => e.message).join('; ')}`,
     )
   }
   const adv = parsed.data?.securityAdvisory
   if (!adv) {
-    throw new ErrorCtor(`GHSA ${ghsaId} not found via GraphQL`)
+    throw new ErrorCtor(`GHSA ${ghsaId} not found`)
   }
   return {
     ghsaId: adv.ghsaId,

src/releases/github.ts

@@ -384,11 +384,7 @@ export async function downloadGitHubRelease(
   if (explicitTag) {
     tag = explicitTag
   } else if (toolPrefix) {
-    const latestTag = await getLatestRelease(
-      toolPrefix,
-      { owner, repo },
-      { quiet },
-    )
+    const latestTag = await getLatestRelease(toolPrefix, { owner, repo })
     if (!latestTag) {
       throw new Error(`No ${toolPrefix} release found in ${owner}/${repo}`)
     }
@@ -495,12 +491,10 @@ export async function downloadReleaseAsset(
   const { quiet = false } = options
 
   // Get the browser_download_url for the asset.
-  const downloadUrl = await getReleaseAssetUrl(
-    tag,
-    assetPattern,
-    { owner, repo },
-    { quiet },
-  )
+  const downloadUrl = await getReleaseAssetUrl(tag, assetPattern, {
+    owner,
+    repo,
+  })
 
   if (!downloadUrl) {
     const patternDesc =
@@ -593,7 +587,9 @@ async function fetchReleasesViaRest(
     { headers: getAuthHeaders() },
   )
   if (!response.ok) {
-    throw new ErrorCtor(`Failed to fetch releases: ${response.status}`)
+    throw new ErrorCtor(
+      `Failed to fetch ${owner}/${repo} releases: ${response.status}`,
+    )
   }
   const text = response.body.toString('utf8')
   if (text.length === 0) {
@@ -607,10 +603,9 @@ async function fetchReleasesViaRest(
   try {
     parsed = JSONParse(text)
   } catch (cause) {
-    throw new ErrorCtor(
-      `Failed to parse GitHub releases response from https://api.github.com/repos/${owner}/${repo}/releases`,
-      { cause },
-    )
+    throw new ErrorCtor(`Failed to parse ${owner}/${repo} releases response`, {
+      cause,
+    })
   }
   return ArrayIsArray(parsed) ? (parsed as ReleaseRow[]) : []
 }
@@ -667,7 +662,7 @@ async function fetchReleasesViaGraphQL(
   })
   if (!response.ok) {
     throw new ErrorCtor(
-      `Failed to fetch releases via GraphQL: ${response.status}`,
+      `Failed to fetch ${owner}/${repo} releases (GraphQL): ${response.status}`,
     )
   }
   let parsed: {
@@ -694,7 +689,7 @@ async function fetchReleasesViaGraphQL(
   }
   if (parsed.errors?.length) {
     throw new ErrorCtor(
-      `GraphQL error: ${parsed.errors.map(e => e.message).join('; ')}`,
+      `GraphQL repository.releases(${owner}/${repo}) returned errors: ${parsed.errors.map(e => e.message).join('; ')}`,
     )
   }
   return (parsed.data?.repository?.releases?.nodes ?? []).map(n => ({
@@ -757,12 +752,12 @@ async function fetchReleaseAssetsViaGraphQL(
   })
   if (!response.ok) {
     throw new ErrorCtor(
-      `GraphQL fallback for ${tag} failed: ${response.status} ${response.statusText}`,
+      `Failed to fetch ${owner}/${repo} release ${tag} (GraphQL): ${response.status} ${response.statusText}`,
     )
   }
   if (response.body.byteLength === 0) {
     throw new ErrorCtor(
-      `GraphQL fallback for ${tag} also returned empty body — both REST and GraphQL backends are degraded`,
+      `Failed to fetch ${owner}/${repo} release ${tag}: GraphQL returned empty body`,
     )
   }
   let parsed: {
@@ -782,13 +777,13 @@ async function fetchReleaseAssetsViaGraphQL(
     parsed = JSONParse(response.body.toString('utf8'))
   } catch (cause) {
     throw new ErrorCtor(
-      `Failed to parse GitHub GraphQL release response for ${tag}`,
+      `Failed to parse ${owner}/${repo} release ${tag} response (GraphQL)`,
       { cause },
     )
   }
   if (parsed.errors?.length) {
     throw new ErrorCtor(
-      `GraphQL error fetching release ${tag}: ${parsed.errors.map(e => e.message).join('; ')}`,
+      `GraphQL repository.release(${owner}/${repo}, ${tag}) returned errors: ${parsed.errors.map(e => e.message).join('; ')}`,
     )
   }
   const release = parsed.data?.repository?.release
@@ -813,7 +808,6 @@ async function fetchReleaseAssetsViaGraphQL(
  * @param options - Additional options
  * @param options.assetPattern - Optional pattern to filter releases by matching asset
  * @param options.nothrow - If true, return undefined instead of throwing when both REST and GraphQL backends are degraded. Default: false.
- * @param options.quiet - Accepted for backward compat; no longer consumed.
  * @returns Latest release tag or undefined if not found
  * @throws {Error} If both REST and GraphQL backends are degraded and nothrow is false.
  *
@@ -831,11 +825,12 @@ export async function getLatestRelease(
   options: {
     assetPattern?: AssetPattern
     nothrow?: boolean
-    quiet?: boolean
   } = {},
 ): Promise<string | undefined> {
-  // `quiet` is accepted for backward compat but no longer consumed —
-  // the helper is silent by design now (errors throw, success returns).
+  // The `quiet` option from previous releases is no longer accepted.
+  // The helper is silent by design now (errors throw, success
+  // returns) so there's nothing for the caller to suppress. Type
+  // enforces this — passing `{ quiet: true }` is a TS error.
   const { assetPattern, nothrow = false } = options
   const { owner, repo } = repoConfig
 
@@ -943,7 +938,6 @@ export async function getLatestRelease(
  * @param repoConfig - Repository configuration (owner/repo)
  * @param options - Additional options
  * @param options.nothrow - If true, return undefined instead of throwing when both REST and GraphQL backends are degraded. Default: false.
- * @param options.quiet - Accepted for backward compat; no longer consumed.
  * @returns Browser download URL for the asset, or undefined when not found.
  * @throws {Error} If both REST and GraphQL backends are degraded and nothrow is false.
  *
@@ -959,8 +953,11 @@ export async function getReleaseAssetUrl(
   tag: string,
   assetPattern: string | AssetPattern,
   repoConfig: RepoConfig,
-  options: { nothrow?: boolean; quiet?: boolean } = {},
+  options: { nothrow?: boolean } = {},
 ): Promise<string | undefined> {
+  // The `quiet` option from previous releases is no longer accepted.
+  // The helper is silent by design now (errors throw, success
+  // returns). Type enforces this — passing `{ quiet: true }` is a TS error.
   const { nothrow = false } = options
   const { owner, repo } = repoConfig
 
@@ -982,7 +979,9 @@ export async function getReleaseAssetUrl(
       )
 
       if (!response.ok) {
-        throw new Error(`Failed to fetch release ${tag}: ${response.status}`)
+        throw new ErrorCtor(
+          `Failed to fetch ${owner}/${repo} release ${tag}: ${response.status}`,
+        )
       }
 
       // -------------------------------------------------------
@@ -1034,9 +1033,7 @@ export async function getReleaseAssetUrl(
           if (nothrow) {
             return undefined
           }
-          throw new ErrorCtor(
-            `Release ${tag} not found in ${owner}/${repo}: GraphQL fallback found no release with that tag`,
-          )
+          throw new ErrorCtor(`Release ${tag} not found in ${owner}/${repo}`)
         }
         assets = fallbackAssets
       } else {
@@ -1047,13 +1044,15 @@ export async function getReleaseAssetUrl(
           release = JSONParse(response.body.toString('utf8'))
         } catch (cause) {
           throw new ErrorCtor(
-            `Failed to parse GitHub release response for tag ${tag}`,
+            `Failed to parse ${owner}/${repo} release ${tag} response`,
             { cause },
           )
         }
 
         if (!ArrayIsArray(release.assets)) {
-          throw new ErrorCtor(`Release ${tag} has no assets`)
+          throw new ErrorCtor(
+            `Release ${tag} has no assets in ${owner}/${repo}`,
+          )
         }
         assets = release.assets
       }

src/releases/socket-btm.ts

@@ -233,7 +233,6 @@ export async function downloadSocketBtmRelease(
       resolvedTag =
         (await getLatestRelease(toolPrefix, SOCKET_BTM_REPO, {
           assetPattern: asset,
-          quiet,
         })) ?? undefined
 
       if (!resolvedTag) {
@@ -244,9 +243,6 @@ export async function downloadSocketBtmRelease(
         resolvedTag,
         asset,
         SOCKET_BTM_REPO,
-        {
-          quiet,
-        },
       )
 
       if (!assetUrl) {

test/unit/github.test.mts

@@ -703,7 +703,7 @@ describe.sequential('github', () => {
 
       await expect(
         resolveRefToSha('owner', 'repo', 'nonexistent'),
-      ).rejects.toThrow('failed to resolve ref')
+      ).rejects.toThrow('Failed to resolve ref')
     })
 
     it('should fall back to GraphQL when REST returns 200 + empty body', async () => {
@@ -827,14 +827,14 @@ describe.sequential('github', () => {
 
       await expect(
         resolveRefToSha('owner', 'repo', 'genuinely-missing-ref'),
-      ).rejects.toThrow('failed to resolve ref')
+      ).rejects.toThrow('Failed to resolve ref')
     })
 
     it('should re-throw original REST error when GraphQL fallback also fails', async () => {
       // Both transports degraded: REST hits empty bodies all the way
       // through the cascade, GraphQL returns a non-OK status. The
       // helper should swallow the GraphQL transport error and
-      // surface the REST cascade's 'failed to resolve ref' message
+      // surface the REST cascade's 'Failed to resolve ref' message
       // — that's more actionable for the user than a confusing
       // GraphQL-side error caused by the same incident.
       nock('https://api.github.com')
@@ -849,7 +849,7 @@ describe.sequential('github', () => {
 
       await expect(
         resolveRefToSha('owner', 'repo', 'double-failure-ref'),
-      ).rejects.toThrow('failed to resolve ref')
+      ).rejects.toThrow('Failed to resolve ref')
     })
 
     it('should return undefined from GraphQL when ref not found anywhere', async () => {
@@ -876,7 +876,7 @@ describe.sequential('github', () => {
 
       await expect(
         resolveRefToSha('owner', 'repo', 'incident-but-real-404'),
-      ).rejects.toThrow('failed to resolve ref')
+      ).rejects.toThrow('Failed to resolve ref')
     })
 
     it('should forward auth token to GraphQL fallback', async () => {