trim comments

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

src/logger/sentry/network-errors.test.ts

@@ -15,10 +15,7 @@ function statusOnlyError(status: number) {
   return new XrpcResponseError(method, new Response(null, {status}), undefined)
 }
 
-/**
- * An `XrpcResponseError` as the PDS pipethrough produces it: the status is
- * rewritten while the upstream lexicon code is forwarded verbatim.
- */
+/** A pipethrough `XrpcResponseError`: status rewritten, code forwarded. */
 function payloadError(status: number, error: string, message: string) {
   const body = {error, message}
   return new XrpcResponseError(
@@ -92,10 +89,7 @@ describe('isExpectedSentryNetworkError', () => {
 
 describe('dropExpectedNetworkErrors', () => {
   test('drops automatic captures using the original exception', () => {
-    /*
-     * The serialized values do not carry the cause chain, so the hint is the
-     * only place the transport failure is visible.
-     */
+    // the serialized values carry no cause chain, only the hint has the failure
     const event = exceptionEvent(
       'XrpcInternalError',
       'Unable to fulfill XRPC request',

src/logger/sentry/network-errors.ts

@@ -4,29 +4,19 @@ import {type ErrorEvent} from '@sentry/react-native'
 import {isNetworkError, safeStringify} from '#/lib/network-error'
 
 /**
- * HTTP statuses that mean an upstream service was unavailable.
- *
- * Matched on the status rather than the lexicon code because the code is not
- * reliable here: the PDS pipethrough rewrites the status to 502 while
- * forwarding the upstream error code verbatim, so an upstream 500 arrives as a
- * 502 still named `InternalServerError`. The status is authoritative.
- *
- * `#/lib/xrpc-error` is deliberately not used for the `instanceof` check - it
- * imports `#/lexicons`, which would pull the whole lexicon graph into the
- * module evaluated before `Sentry.init()`.
+ * Upstream-unavailable statuses. Matched on the status, not the lexicon
+ * code: the PDS pipethrough rewrites the status to 502 but forwards the
+ * upstream code verbatim, so a 502 can arrive named `InternalServerError`.
+ * `#/lib/xrpc-error` is deliberately not imported - it pulls `#/lexicons`
+ * into the module graph evaluated before `Sentry.init()`.
  */
 const TRANSIENT_UPSTREAM_STATUSES = new Set([502, 503, 504])
 
 /**
- * Sentry serializes an exception as `{type: error.name, value: error.message}`,
- * so these match the message text rather than the `toString()`. Lex builds that
- * message from the server's error payload ("Upstream Timeout") or, when the
- * response carries no JSON payload, from the status alone ("Upstream server
- * responded with a 504 error").
- *
- * The optional space matches the spaced prose and the space-free lexicon code
- * ("UpstreamFailure") alike, and the word boundaries keep camelCase
- * identifiers such as `upstreamTimeoutV2` from matching.
+ * Sentry serializes `error.message`, not `toString()`, so these match the
+ * message text: the payload message ("Upstream Timeout"), the lexicon code
+ * ("UpstreamFailure"), and lex's payload-less "Upstream server responded with
+ * a 504 error". Word boundaries keep camelCase identifiers from matching.
  */
 const TRANSIENT_UPSTREAM_MESSAGES = [
   /\bupstream\s?failure\b/i,
@@ -64,11 +54,9 @@ export function isExpectedSentryNetworkError(value: unknown): boolean {
 /**
  * Global backstop for automatic captures that bypass the logger transport.
  *
- * Only exception events are inspected. Sentry sets `hint.originalException` to
- * the message *string* for a `captureMessage`, and message events reach Sentry
- * from exactly two places: the logger transport, which has already run this
- * check before capturing, and user bug reports, which must never be dropped
- * for happening to contain a word like "aborted" in the report slug.
+ * Message events are skipped: Sentry sets `hint.originalException` to the
+ * message string for `captureMessage`, and the only message producers are the
+ * logger transport (already filtered) and user bug reports (never droppable).
  */
 export function dropExpectedNetworkErrors(
   event: ErrorEvent,

src/logger/transports/sentry.ts

@@ -3,20 +3,14 @@ import {isExpectedSentryNetworkError} from '#/logger/sentry/network-errors'
 import {LogLevel, type Metadata, type Transport} from '#/logger/types'
 import {prepareMetadata} from '#/logger/util'
 
-/**
- * Metadata keys that have historically carried the underlying failure as a
- * plain string.
- */
+/** Keys that have historically carried the underlying failure as a plain string. */
 const CHECKED_METADATA_KEYS = ['safeMessage', 'message', 'error']
 
 /**
  * Whether this log records a network failure Sentry should not be told about.
- *
- * The failure is often passed in metadata rather than as the message, and call
- * sites do not consistently use the same key, so any `Error` value counts no
- * matter which key holds it. Values of other types only count under the keys
- * above: metadata is arbitrary, and scanning all of it lets an unrelated string
- * - a stream URL containing "abort", say - suppress a real error.
+ * Call sites do not agree on a metadata key, so any `Error` value counts under
+ * any key; other types only count under `CHECKED_METADATA_KEYS` - scanning all
+ * metadata lets an unrelated string (a URL with "abort") suppress a real error.
  */
 function isExpectedNetworkFailure(
   message: string | Error,
@@ -45,11 +39,7 @@ export const sentryTransport: Transport = (
   // Skip debug messages entirely for now - esb
   if (level === LogLevel.Debug) return
 
-  /*
-   * `__metadata__` is ambient context rather than something the call site
-   * passed, so it is destructured out of the scanned metadata and folded back
-   * in here to keep the attached data unchanged.
-   */
+  // ambient __metadata__ is kept out of the scan but stays in the attached data
   const meta = {
     __context__: context,
     ...prepareMetadata(__metadata__ ? {__metadata__, ...metadata} : metadata),