refactor: trim comments to why-only

Removes signature restatements, numbered gate lists that narrate the code below
them, and the four copies of the destination-url rationale now documented once
on RouteName.url. Framework quirks, ordering invariants and deliberate
deviations stay, compressed.

Also merges the two stacked JSDoc blocks on createIdentityTagger and re-homes
the resolveRejectionEnabler doc that the previous commit's extraction left
sitting above the wrong function.

Author: DriesH

packages/core/src/Flare.ts

@@ -69,11 +69,11 @@ export class Flare {
     private framework: Framework | null = null;
 
     /**
-     * @param contextCollector returns per-report attributes (browser DOM, Node process, etc). No-op by default.
-     * @param fileReader       reads source files for stack-trace snippets. Default returns null (no snippets);
+     * @param contextCollector per-report attributes (browser DOM, Node process). No-op by default.
+     * @param fileReader       source files for stack-trace snippets. Defaults to no snippets;
      *                         `@flareapp/js` injects a fetch reader, `@flareapp/node` a disk reader.
-     * @param scopeProvider    returns the current `Scope` (glows, pendingAttributes, entryPoint). Browser uses one
-     *                         global scope; Node uses an AsyncLocalStorage-backed provider so each request gets its own.
+     * @param scopeProvider    the current `Scope`. Browser uses one global scope; Node an
+     *                         AsyncLocalStorage-backed provider so each request gets its own.
      */
     constructor(
         public api: Api = new Api(),
@@ -107,14 +107,12 @@ export class Flare {
     }
 
     /**
-     * Register an in-flight report so `flush()` can wait for it. Called by every public report entry point, each
-     * wrapping its full async pipeline (beforeEvaluate -> stack trace -> beforeSubmit -> api.report) so the whole
-     * roundtrip is tracked, not just the HTTP send.
+     * Register an in-flight report so `flush()` can wait for it. Every entry point wraps its whole async
+     * pipeline (beforeEvaluate -> stack trace -> beforeSubmit -> api.report), not just the HTTP send.
      *
-     * Stores a shadow promise that mirrors `p`'s timing but cannot reject (the `() => undefined` rejection handler
-     * consumes any failure), so an unhandled report rejection never surfaces as a Node warning / console error. The
-     * shadow self-removes from the Set via `.finally`; `delete` never throws, so wrap any richer cleanup in try/catch.
-     * Returns the original `p` so the caller still observes real success/failure; tracking is invisible to them.
+     * What goes in the Set is a shadow promise that mirrors `p`'s timing but cannot reject, so a failed
+     * report never surfaces as an unhandled rejection warning. `p` itself is returned untouched, so the
+     * caller still observes real success or failure.
      */
     private track<T>(p: Promise<T>): Promise<T> {
         const tracked = p.then(
@@ -127,14 +125,12 @@ export class Flare {
     }
 
     /**
-     * Wait until every in-flight report settles or `timeoutMs` elapses, whichever comes first. Always resolves, never
-     * rejects; no retry. Main consumer is `@flareapp/node`'s fatal handler, which awaits the fatal report explicitly
-     * then calls flush to drain any OTHER concurrent reports before `process.exit`.
+     * Wait until every in-flight report settles or `timeoutMs` elapses. Always resolves, never rejects.
+     * Written for `@flareapp/node`'s fatal handler, which awaits the fatal report itself then flushes to
+     * drain any other concurrent reports before `process.exit`.
      *
-     * `[...this.inflight]` snapshots the Set: reports started after this line are NOT awaited, which bounds the wait so
-     * a handler emitting reports during shutdown cannot block the process forever. Call flush again to drain those.
-     * `allSettled` (not `all`) waits for every report regardless of HTTP success/failure; `all` would short-circuit on
-     * the first rejection. Flush does not stop new reports; the instance stays usable afterward.
+     * Snapshotting the Set bounds the wait: reports started after this line are not awaited, so a handler
+     * that keeps emitting during shutdown cannot block the process forever. Call flush again for those.
      */
     flush(timeoutMs = 2000): Promise<void> {
         this._logger.flush();
@@ -200,9 +196,8 @@ export class Flare {
             this._config.tracesSampleRate = Math.max(0, Math.min(1, config.tracesSampleRate));
         }
 
-        // Only re-resolve the denylist when this call actually carries denylist config. Otherwise the spread
-        // above already preserved the previously resolved denylist, and re-resolving with an undefined `custom`
-        // would clobber a custom denylist back to the default, silently re-exposing data the user asked to redact.
+        // Only when this call carries denylist config. Re-resolving with an undefined `custom` would reset a
+        // custom denylist to the default, silently re-exposing data the user asked to redact.
         if (config.urlDenylist !== undefined || config.replaceDefaultUrlDenylist !== undefined) {
             this._config.urlDenylist = resolveDenylist(
                 config.urlDenylist,
@@ -278,11 +273,8 @@ export class Flare {
     }
 
     /**
-     * Attach an identified user to the active scope. Fields are projected to the
-     * keys the Flare backend reads: `user.id`, `user.email`, `user.full_name`,
-     * and `client.address`. Any extra keys are bundled into `user.attributes`.
-     * Pass `null` to clear the user. Scope-aware: in Node this targets the
-     * per-request scope via the scope provider.
+     * Projects the known fields to the keys the Flare backend reads (see `USER_FIELD_KEYS`) and bundles
+     * anything else into `user.attributes`. Pass `null` to clear. In Node this targets the per-request scope.
      */
     setUser(user: User | null): this {
         const scope = this.scopeProvider.active();
@@ -536,16 +528,15 @@ export class Flare {
         };
     }
 
+    /** Local roots only, snapshotted by the Tracer at span START so a long-lived root does not drift into
+     *  the next page's scope. Children get none, and no span ever runs the DOM collector. */
     private getScopeAttributes(): Attributes {
-        // Scope-derived record a LOCAL ROOT span carries: user context, entry-point overrides,
-        // framework-in-context.custom. Tracer snapshots this at span START so a long-lived root does not drift into the
-        // next page's scope. Spans never run the DOM collector; children get no scope. Mirrors the PHP client.
         return this.assembleAttributes({}, {}, false);
     }
 
     private spanResourceAttributes(): Attributes {
-        // Resource is stable per page (host.name). Keep only the collector's resource partition, dropping record-level
-        // context (cookies/url) so nothing heavy or drifting reaches spans. Evaluated once per flush, not per span.
+        // Only the resource partition: record-level context (cookies, url) is heavy and drifts, and this is
+        // evaluated once per flush rather than per span.
         return partitionAttributes(this.contextCollector(this._config)).resource;
     }
 
@@ -562,9 +553,8 @@ export class Flare {
         const activeScope = this.scopeProvider.active();
         const attributes = this.assembleAttributes(this.contextCollector(this._config), input.extraAttributes, true);
 
-        // seenAtUnixNano in real nanoseconds. Date.now() * 1_000_000 exceeds MAX_SAFE_INTEGER by ~3 bits (~256 ns), but
-        // browser clocks are millisecond-precision so the lost bits are below source resolution. PHP's json_decode
-        // reads the 19-digit literal as a 64-bit int (PHP_INT_MAX ~9.22e18 vs our ~1.78e18).
+        // seenAtUnixNano overflows MAX_SAFE_INTEGER by ~3 bits (~256ns), which is below the millisecond
+        // resolution browser clocks actually have. PHP reads the 19-digit literal as a 64-bit int.
         const report: Report = {
             exceptionClass: input.exceptionClass,
             message: input.message,

packages/core/src/Scope.ts

@@ -1,27 +1,18 @@
 import type { Attributes, AttributeValue, EntryPointHandler, Glow } from './types';
 
-/**
- * Maps each `User` identity field to the flat report attribute key it projects to. `Flare.setUser` writes through
- * these; `USER_IDENTITY_KEYS` (the clear pass) derives from them, so a new field can never leave the clear pass stale.
- */
+/** `USER_IDENTITY_KEYS` derives from this, so adding a field here can never leave the clear pass stale. */
 export const USER_FIELD_KEYS = {
     id: 'user.id',
     email: 'user.email',
     fullName: 'user.full_name',
     ipAddress: 'client.address',
 } as const;
 
-/**
- * Attribute keys `Flare.setUser` owns: the four projected identity fields plus the `user.attributes` bag. Single
- * source of truth so the set/clear passes cannot drift, and so consumers stamping identity outside core's report
- * pipeline (Electron's forwarded-renderer path) reuse the exact same set.
- */
+/** Every key `Flare.setUser` owns. Consumers stamping identity outside core's report pipeline (Electron's
+ *  forwarded-renderer path) reuse this exact set. */
 export const USER_IDENTITY_KEYS = [...Object.values(USER_FIELD_KEYS), 'user.attributes'] as const;
 
-/**
- * Pick the user-identity attributes currently set on a scope. Used where identity must be copied onto a report that
- * does not flow through `Flare.report()` (which would otherwise spread `pendingAttributes` automatically).
- */
+/** For reports that do not flow through `Flare.report()`, which would spread `pendingAttributes` itself. */
 export function userIdentityAttributes(scope: Scope): Attributes {
     const attrs: Attributes = {};
     for (const key of USER_IDENTITY_KEYS) {
@@ -34,23 +25,16 @@ export function userIdentityAttributes(scope: Scope): Attributes {
 }
 
 /**
- * Per-call mutable state: breadcrumbs (`glows`), custom attributes (`pendingAttributes`), and the current entry-point
- * handler. Split out of `Flare` so the consumer can choose a single global `Scope` (browser, one user at a time) or one
- * `Scope` per request via AsyncLocalStorage (Node, concurrent requests must not leak into each other). `Flare` reaches
- * it through `scopeProvider.active()`, so per-request behavior lives in the provider.
- *
- * `NodeScope` (in `@flareapp/node`) extends this with a `request` bucket (method, path, headers). User identity goes to
- * `pendingAttributes` via `Flare.setUser`, so it needs no dedicated field.
+ * Per-call mutable state, split out of `Flare` so the consumer can choose one global `Scope` (browser, one
+ * user at a time) or one per request via AsyncLocalStorage (Node, where concurrent requests must not leak
+ * into each other). `@flareapp/node`'s `NodeScope` extends this with a `request` bucket.
  */
 export class Scope {
     glows: Glow[] = [];
     pendingAttributes: Attributes = {};
     entryPoint: EntryPointHandler | null = null;
 
-    /**
-     * Append a breadcrumb, capping the list at `maxGlowsPerReport` by dropping the oldest entries. Keeps the payload
-     * bounded while preserving the most recent events leading up to an error.
-     */
+    /** Caps at `maxGlowsPerReport` by dropping the oldest, so the payload stays bounded. */
     addGlow(glow: Glow, maxGlowsPerReport: number): void {
         this.glows.push(glow);
         if (this.glows.length > maxGlowsPerReport) {
@@ -62,34 +46,26 @@ export class Scope {
         this.glows = [];
     }
 
-    /** Set a single attribute (`Flare.addContext` / `addContextGroup`). Last write wins. */
     setAttribute(key: string, value: AttributeValue): void {
         this.pendingAttributes[key] = value;
     }
 
-    /**
-     * Shallow-merge attributes into this scope. Used by Node's provider when patching live request context via
-     * `flare.mergeContext({ ... })`. Last write wins per key; nested objects are not deep-merged.
-     */
+    /** Shallow: last write wins per key, nested objects are not deep-merged. */
     mergeAttributes(partial: Attributes): void {
         Object.assign(this.pendingAttributes, partial);
     }
 }
 
 /**
  * The seam through which `Flare` reaches its current `Scope`; implementations decide what "current" means.
- * `GlobalScopeProvider` always returns the same instance (browser); `@flareapp/node`'s provider returns the
- * per-request `NodeScope` from `node:async_hooks`, falling back to a shared scope outside any `runWithContext(...)`.
- * Consumers may supply their own.
+ * `@flareapp/node`'s returns the per-request `NodeScope` from `node:async_hooks`, falling back to a shared
+ * scope outside any `runWithContext(...)`.
  */
 export interface ScopeProvider {
     active(): Scope;
 }
 
-/**
- * One `Scope` for the provider's lifetime, shared by every caller. Right default for single-context environments
- * (browser tab, CLI script) and the fallback `Flare`'s constructor uses when no provider is supplied.
- */
+/** One `Scope` for the provider's lifetime. The right default for a browser tab or a CLI script. */
 export class GlobalScopeProvider implements ScopeProvider {
     private scope = new Scope();
     active(): Scope {

packages/core/src/util/createIdentityTagger.ts

@@ -8,13 +8,12 @@ export interface SdkTaggable {
 }
 
 /**
- * Builds a per-package SDK/framework identity tagger. Holds its own WeakSet guards so each Flare
- * instance (singleton or injected renderer) is tagged at most once, on each of the two axes.
- */
-/**
- * `frameworkName` is typed as `FrameworkName`, not `string`: this is the wire vocabulary the backend
- * keys off, so a first-party package cannot invent a value here. A host app that genuinely needs its
- * own name calls `setFramework` directly.
+ * A per-package SDK/framework identity tagger. Holds its own WeakSet guards, so each Flare instance
+ * (singleton or injected renderer) is tagged at most once on each of the two axes.
+ *
+ * `frameworkName` is `FrameworkName` rather than `string` because that is the wire vocabulary the backend
+ * keys off, so a first-party package cannot invent a value. A host app that needs its own name calls
+ * `setFramework` directly.
  */
 export function createIdentityTagger(config: { sdkName: string; sdkVersion: string; frameworkName: FrameworkName }): {
     registerSdkIdentity(flare: SdkTaggable): void;

packages/core/src/util/rejection.ts

@@ -1,14 +1,10 @@
-/**
- * Shared unhandled-rejection routing. A rejection reason can be anything a promise rejected with: an Error, a
- * stack-bearing object, a string, or a plain object. The browser `unhandledrejection` listener (`@flareapp/js`) and the
- * React Native rejection tracker (`@flareapp/react-native`) share this routing so reports look identical across SDKs.
- */
+// Shared by the browser `unhandledrejection` listener and the React Native rejection tracker, so a
+// rejection reports identically across SDKs whatever it was rejected with.
 
 export type RejectionReporter = {
-    // Error / stack-bearing reasons: preserve the stack.
+    /** Error / stack-bearing reasons: preserve the stack. */
     reportSilently: (error: Error) => void;
-    // Stackless reasons: empty-stack `UnhandledRejection` shaping. May return a promise (core's does);
-    // `routeRejection` swallows any rejection from it.
+    /** Stackless reasons. May return a promise; `routeRejection` swallows any rejection from it. */
     reportUnhandledRejection: (message: string) => unknown;
 };
 
@@ -19,7 +15,7 @@ export function describeRejectionReason(reason: unknown): string {
     }
     if (reason && typeof reason === 'object') {
         const message = (reason as { message?: unknown }).message;
-        // An empty `.message` carries no signal; fall through to JSON.stringify so the report shows the object's shape.
+        // An empty `.message` carries no signal, so fall through and let JSON.stringify show the shape.
         if (typeof message === 'string' && message) {
             return message;
         }
@@ -37,10 +33,8 @@ function hasStack(reason: unknown): reason is { stack: string } {
 }
 
 /**
- * Route a rejection reason: an Error (or any stack-bearing object) goes to `reportSilently` so the stack survives; a
- * stackless reason falls back to `reportUnhandledRejection` (string message, empty-stack `UnhandledRejection`). Any
- * rejection from `reportUnhandledRejection`'s promise is swallowed so a transport failure cannot itself surface as an
- * unhandled rejection. `reportSilently` is assumed async and not wrapped, so a synchronous throw there would propagate.
+ * The `.catch` is what stops a transport failure from surfacing as a second unhandled rejection.
+ * `reportSilently` is assumed async and left unwrapped, so a synchronous throw there still propagates.
  */
 export function routeRejection(reporter: RejectionReporter, reason: unknown): void {
     if (reason instanceof Error) {