bippy 0.5.43 → 0.6.0

package/src/source/parse-debug-stack.ts

@@ -0,0 +1,133 @@
+import { JSX_FACTORY_FRAME_COUNT, REACT_STACK_BOTTOM_FRAME_PATTERNS } from "./constants.js";
+import { parseStack, StackFrame } from "./parse-stack.js";
+
+interface V8CallSite {
+  getFunctionName?: () => string | null;
+  getScriptNameOrSourceURL?: () => string | null;
+  getLineNumber?: () => number | null;
+  getColumnNumber?: () => number | null;
+  getEnclosingLineNumber?: () => number | null;
+  getEnclosingColumnNumber?: () => number | null;
+  getTypeName?: () => string | null;
+  getMethodName?: () => string | null;
+  getEvalOrigin?: () => string | null;
+  isNative?: () => boolean;
+  isEval?: () => boolean;
+  toString: () => string;
+}
+
+export interface ParsedDebugStack {
+  frames: StackFrame[];
+  // React appends a react-stack-bottom-frame sentinel to stacks captured
+  // during render; without it the JSX was created outside a render and the
+  // lower frames are arbitrary bootstrapping code
+  isTrusted: boolean;
+}
+
+const parsedDebugStackCache = new WeakMap<Error, ParsedDebugStack>();
+
+const isReactBottomFrameName = (functionName: string): boolean =>
+  REACT_STACK_BOTTOM_FRAME_PATTERNS.some((pattern) => functionName.includes(pattern));
+
+const getCallSiteFunctionName = (callSite: V8CallSite): string => {
+  const functionName = callSite.getFunctionName?.() ?? "";
+  if (functionName) {
+    return functionName;
+  }
+  const typeName = callSite.getTypeName?.() ?? "";
+  const methodName = callSite.getMethodName?.() ?? "";
+  if (typeName && methodName) {
+    return `${typeName}.${methodName}`;
+  }
+  return methodName;
+};
+
+const collectStructuredFrames = (callSites: V8CallSite[]): ParsedDebugStack => {
+  const frames: StackFrame[] = [];
+  for (
+    let callSiteIndex = JSX_FACTORY_FRAME_COUNT;
+    callSiteIndex < callSites.length;
+    callSiteIndex++
+  ) {
+    const callSite = callSites[callSiteIndex];
+    const functionName = getCallSiteFunctionName(callSite);
+    if (isReactBottomFrameName(functionName)) {
+      return { frames, isTrusted: true };
+    }
+    if (callSite.isNative?.()) {
+      frames.push({ functionName: functionName || undefined });
+      continue;
+    }
+    let fileName = callSite.getScriptNameOrSourceURL?.() ?? "";
+    if (!fileName && callSite.isEval?.()) {
+      fileName = callSite.getEvalOrigin?.() ?? "";
+    }
+    frames.push({
+      functionName: functionName && functionName !== "<anonymous>" ? functionName : undefined,
+      fileName: fileName && fileName !== "<anonymous>" ? fileName : undefined,
+      lineNumber: callSite.getLineNumber?.() ?? undefined,
+      columnNumber: callSite.getColumnNumber?.() ?? undefined,
+      enclosingLineNumber: callSite.getEnclosingLineNumber?.() ?? undefined,
+      enclosingColumnNumber: callSite.getEnclosingColumnNumber?.() ?? undefined,
+      source: `    at ${callSite.toString()}`,
+    });
+  }
+  return { frames, isTrusted: false };
+};
+
+const parseMaterializedStack = (stackString: string): ParsedDebugStack => {
+  let bottomFrameIndex = -1;
+  for (const pattern of REACT_STACK_BOTTOM_FRAME_PATTERNS) {
+    bottomFrameIndex = stackString.indexOf(pattern);
+    if (bottomFrameIndex !== -1) break;
+  }
+  const trimmedStack =
+    bottomFrameIndex === -1
+      ? stackString
+      : stackString.slice(0, stackString.lastIndexOf("\n", bottomFrameIndex));
+  return {
+    frames: parseStack(trimmedStack).slice(JSX_FACTORY_FRAME_COUNT),
+    isTrusted: bottomFrameIndex !== -1,
+  };
+};
+
+/**
+ * Parses a React `_debugStack` Error, preferring V8's structured CallSite API
+ * (via Error.prepareStackTrace) over string parsing. Structured frames carry
+ * enclosing line/column - the function definition start, not the call site -
+ * and are immune to source-mapped `.stack` strings. Falls back to string
+ * parsing on engines without CallSites (JSC, SpiderMonkey) or when the stack
+ * was already materialized. The leading JSX factory frame (jsxDEV) and
+ * everything at or below React's bottom-frame sentinel are dropped.
+ */
+export const parseDebugStack = (debugStack: Error): ParsedDebugStack => {
+  const cachedResult = parsedDebugStackCache.get(debugStack);
+  if (cachedResult) {
+    return cachedResult;
+  }
+
+  let structuredResult: ParsedDebugStack | null = null;
+  const collectFramesAndFormatStack = (error: Error, callSites: V8CallSite[]): string => {
+    structuredResult = collectStructuredFrames(callSites);
+    // this return value becomes error.stack permanently, so emit the default
+    // V8 format for any later reader of the same error
+    let stackString = `${error.name || "Error"}: ${error.message || ""}`;
+    for (const callSite of callSites) {
+      stackString += `\n    at ${callSite.toString()}`;
+    }
+    return stackString;
+  };
+  const previousPrepareStackTrace = Error.prepareStackTrace;
+  // node's CallSite typings disagree with browser-safe optional methods
+  Error.prepareStackTrace = collectFramesAndFormatStack as typeof Error.prepareStackTrace;
+  let stackString: string;
+  try {
+    stackString = String(debugStack.stack);
+  } finally {
+    Error.prepareStackTrace = previousPrepareStackTrace;
+  }
+
+  const result = structuredResult ?? parseMaterializedStack(stackString);
+  parsedDebugStackCache.set(debugStack, result);
+  return result;
+};

package/src/source/parse-stack.ts

@@ -2,11 +2,17 @@ export interface StackFrame {
   args?: unknown[];
   columnNumber?: number;
   lineNumber?: number;
+  // start of the enclosing function (the definition, not the call site);
+  // only available from V8's structured CallSite API
+  enclosingLineNumber?: number;
+  enclosingColumnNumber?: number;
   fileName?: string;
   functionName?: string;
   source?: string;
   isServer?: boolean;
   isSymbolicated?: boolean;
+  // the source map ignore-listed this frame's original source (x_google_ignoreList)
+  isIgnoreListed?: boolean;
 }
 
 export interface ParseOptions {
@@ -19,14 +25,6 @@ const FIREFOX_SAFARI_STACK_REGEXP = /(^|@)\S+:\d+/;
 const CHROME_IE_STACK_REGEXP = /^\s*at .*(\S+:\d+|\(native\))/m;
 const SAFARI_NATIVE_CODE_REGEXP = /^(eval@)?(\[native code\])?$/;
 
-const getNonStandardStacktrace = (error: unknown): string | null => {
-  if (error && typeof error === "object") {
-    const stacktrace = (error as Record<string, unknown>)["stacktrace"];
-    return typeof stacktrace === "string" ? stacktrace : null;
-  }
-  return null;
-};
-
 export const parseStack = (stackString: string, options?: ParseOptions): StackFrame[] => {
   if (options?.includeInElement !== false) {
     const lines = stackString.split("\n");
@@ -76,10 +74,6 @@ const applySlice = <T>(lines: T[], options?: ParseOptions): T[] => {
   return lines;
 };
 
-export const parseV8OrIE = (error: Error, options?: ParseOptions): StackFrame[] => {
-  return parseV8OrIeString(error.stack!, options);
-};
-
 export const parseV8OrIeString = (stack: string, options?: ParseOptions): StackFrame[] => {
   const filteredLines = applySlice(
     stack.split("\n").filter((line) => {
@@ -120,10 +114,6 @@ export const parseV8OrIeString = (stack: string, options?: ParseOptions): StackF
   });
 };
 
-export const parseFFOrSafari = (error: Error, options?: ParseOptions): StackFrame[] => {
-  return parseFFOrSafariString(error.stack!, options);
-};
-
 export const parseFFOrSafariString = (stack: string, options?: ParseOptions): StackFrame[] => {
   const filteredLines = applySlice(
     stack.split("\n").filter((line) => {
@@ -158,92 +148,3 @@ export const parseFFOrSafariString = (stack: string, options?: ParseOptions): St
     }
   });
 };
-
-export const parseOpera = (error: Error, options?: ParseOptions): StackFrame[] => {
-  const nonStandardStacktrace = getNonStandardStacktrace(error);
-  if (
-    !nonStandardStacktrace ||
-    (error.message.includes("\n") &&
-      error.message.split("\n").length > nonStandardStacktrace.split("\n").length)
-  ) {
-    return parseOpera9(error, options);
-  }
-  if (!error.stack) return parseOpera10(error, options);
-  return parseOpera11(error, options);
-};
-
-export const parseOpera9 = (error: Error, options?: ParseOptions): StackFrame[] => {
-  const lineRegex = /Line (\d+).*script (?:in )?(\S+)/i;
-  const messageLines = error.message.split("\n");
-  const parsedFrames: StackFrame[] = [];
-
-  for (let i = 2, len = messageLines.length; i < len; i += 2) {
-    const match = lineRegex.exec(messageLines[i]);
-    if (match) {
-      parsedFrames.push({
-        fileName: match[2],
-        lineNumber: +match[1],
-        source: messageLines[i],
-      });
-    }
-  }
-
-  return applySlice(parsedFrames, options);
-};
-
-export const parseOpera10 = (error: Error, options?: ParseOptions): StackFrame[] => {
-  const lineRegex = /Line (\d+).*script (?:in )?(\S+)(?:: In function (\S+))?$/i;
-  const nonStandardStacktrace = getNonStandardStacktrace(error);
-  const stacktraceLines = (nonStandardStacktrace || "").split("\n");
-  const parsedFrames: StackFrame[] = [];
-
-  for (let i = 0, len = stacktraceLines.length; i < len; i += 2) {
-    const match = lineRegex.exec(stacktraceLines[i]);
-    if (match) {
-      parsedFrames.push({
-        functionName: match[3] || undefined,
-        fileName: match[2],
-        lineNumber: match[1] ? +match[1] : undefined,
-        source: stacktraceLines[i],
-      });
-    }
-  }
-
-  return applySlice(parsedFrames, options);
-};
-
-export const parseOpera11 = (error: Error, options?: ParseOptions): StackFrame[] => {
-  const filteredLines = applySlice(
-    // @ts-expect-error missing stack property
-    error.stack.split("\n").filter((line) => {
-      return !!line.match(FIREFOX_SAFARI_STACK_REGEXP) && !line.match(/^Error created at/);
-    }),
-    options,
-  );
-
-  return filteredLines.map<StackFrame>((line) => {
-    const tokens = line.split("@");
-    const locationParts = extractLocation(tokens.pop()!);
-    const functionCall = tokens.shift() || "";
-    const functionName =
-      functionCall.replace(/<anonymous function(: (\w+))?>/, "$2").replace(/\([^)]*\)/g, "") ||
-      undefined;
-    let argsRaw: string | undefined;
-    if (functionCall.match(/\(([^)]*)\)/))
-      argsRaw = functionCall.replace(/^[^(]+\(([^)]*)\)$/, "$1");
-
-    const args =
-      argsRaw === undefined || argsRaw === "[arguments not available]"
-        ? undefined
-        : argsRaw.split(",");
-
-    return {
-      functionName,
-      args,
-      fileName: locationParts[0],
-      lineNumber: locationParts[1] ? +locationParts[1] : undefined,
-      columnNumber: locationParts[2] ? +locationParts[2] : undefined,
-      source: line,
-    };
-  });
-};

package/src/source/symbolication.ts

@@ -5,6 +5,7 @@ import { StackFrame } from "./parse-stack.js";
 export interface DecodedSourceMapSection {
   map: {
     file?: string;
+    ignoredSourceIndices?: Set<number>;
     mappings: SourceMapSegment[][];
     names?: string[];
     sourceRoot?: string;
@@ -35,6 +36,7 @@ export type RawSourceMap = IndexSourceMap | StandardSourceMap;
 
 export interface SourceMap {
   file?: string;
+  ignoredSourceIndices?: Set<number>;
   mappings: SourceMapSegment[][];
   names?: string[];
   sections?: DecodedSourceMapSection[];
@@ -47,12 +49,14 @@ export interface SourceMap {
 // https://developer.chrome.com/blog/sourcemaps#the_anatomy_of_a_source_map
 export interface StandardSourceMap {
   file?: string;
+  ignoreList?: number[];
   mappings: string;
   names?: string[];
   sourceRoot?: string;
   sources: string[];
   sourcesContent?: string[];
   version: 3;
+  x_google_ignoreList?: number[];
 }
 
 // has a scheme, e.g. http://, https://, file://, data:, etc.
@@ -77,6 +81,7 @@ const getSourceFromMappings = (
   sources: string[],
   lineIndexInMappings: number,
   column: number,
+  ignoredSourceIndices?: Set<number>,
 ): StackFrame | null => {
   if (lineIndexInMappings < 0 || lineIndexInMappings >= mappings.length) {
     return null;
@@ -87,12 +92,18 @@ const getSourceFromMappings = (
     return null;
   }
 
+  // Segments within a line are sorted by generated column, so binary search for
+  // the last segment at or before the column.
   let closestLineSegment: null | SourceMapSegment = null;
-  for (const lineSegment of lineMapping) {
-    if (lineSegment[0] <= column) {
-      closestLineSegment = lineSegment;
+  let lowIndex = 0;
+  let highIndex = lineMapping.length - 1;
+  while (lowIndex <= highIndex) {
+    const middleIndex = (lowIndex + highIndex) >> 1;
+    if (lineMapping[middleIndex][0] <= column) {
+      closestLineSegment = lineMapping[middleIndex];
+      lowIndex = middleIndex + 1;
     } else {
-      break;
+      highIndex = middleIndex - 1;
     }
   }
 
@@ -116,6 +127,7 @@ const getSourceFromMappings = (
     columnNumber: sourceColumn,
     fileName,
     lineNumber: sourceLine + 1,
+    isIgnoreListed: ignoredSourceIndices?.has(sourceIndex) ?? false,
   };
 };
 
@@ -125,12 +137,14 @@ export const getSourceFromSourceMap = (
   column: number,
 ): StackFrame | null => {
   if (sourceMap.sections) {
+    // Section offsets are 0-based while stack trace lines are 1-based.
+    const lineIndex = line - 1;
     let targetSection: DecodedSourceMapSection | null = null;
 
     for (const section of sourceMap.sections) {
       if (
-        line > section.offset.line ||
-        (line === section.offset.line && column >= section.offset.column)
+        lineIndex > section.offset.line ||
+        (lineIndex === section.offset.line && column >= section.offset.column)
       ) {
         targetSection = section;
       } else {
@@ -142,29 +156,40 @@ export const getSourceFromSourceMap = (
       return null;
     }
 
-    const relativeLine = line - targetSection.offset.line;
+    const relativeLine = lineIndex - targetSection.offset.line;
     const relativeColumn =
-      line === targetSection.offset.line ? column - targetSection.offset.column : column;
+      lineIndex === targetSection.offset.line ? column - targetSection.offset.column : column;
 
     return getSourceFromMappings(
       targetSection.map.mappings,
       targetSection.map.sources,
       relativeLine,
       relativeColumn,
+      targetSection.map.ignoredSourceIndices,
     );
   }
 
-  return getSourceFromMappings(sourceMap.mappings, sourceMap.sources, line - 1, column);
+  return getSourceFromMappings(
+    sourceMap.mappings,
+    sourceMap.sources,
+    line - 1,
+    column,
+    sourceMap.ignoredSourceIndices,
+  );
 };
 
 const getSourceMapUrl = (url: string, content: string): null | string => {
-  const lines = content.split("\n");
+  // Walk lines backwards without content.split("\n"), which would allocate a
+  // string per line of the entire bundle.
   let sourceMapUrl: string | undefined;
-  for (let i = lines.length - 1; i >= 0 && !sourceMapUrl; i--) {
-    const regexMatch = lines[i].match(SOURCEMAP_REGEX);
+  let searchEnd = content.length;
+  while (searchEnd > 0 && !sourceMapUrl) {
+    const lineStart = content.lastIndexOf("\n", searchEnd - 1) + 1;
+    const regexMatch = content.slice(lineStart, searchEnd).match(SOURCEMAP_REGEX);
     if (regexMatch) {
       sourceMapUrl = regexMatch[1] || regexMatch[2];
     }
+    searchEnd = lineStart - 1;
   }
 
   if (!sourceMapUrl) {
@@ -181,8 +206,14 @@ const getSourceMapUrl = (url: string, content: string): null | string => {
   return sourceMapUrl;
 };
 
+const getIgnoredSourceIndices = (rawSourceMap: StandardSourceMap): Set<number> | undefined => {
+  const ignoreList = rawSourceMap.ignoreList ?? rawSourceMap.x_google_ignoreList;
+  return Array.isArray(ignoreList) && ignoreList.length > 0 ? new Set(ignoreList) : undefined;
+};
+
 const decodeStandardSourceMap = (rawSourceMap: StandardSourceMap): SourceMap => ({
   file: rawSourceMap.file,
+  ignoredSourceIndices: getIgnoredSourceIndices(rawSourceMap),
   mappings: decode(rawSourceMap.mappings),
   names: rawSourceMap.names,
   sourceRoot: rawSourceMap.sourceRoot,
@@ -196,6 +227,7 @@ const decodeIndexSourceMap = (rawSourceMap: IndexSourceMap): SourceMap => {
     ({ map, offset }) => ({
       map: {
         ...map,
+        ignoredSourceIndices: getIgnoredSourceIndices(map),
         mappings: decode(map.mappings),
       },
       offset,
@@ -268,7 +300,9 @@ export const getSourceMapImpl = async (
   const sourceMapUrl = getSourceMapUrl(bundleUrl, bundleContent);
 
   if (!sourceMapUrl) return null;
-  if (!isFetchableUrl(sourceMapUrl)) {
+  // inline data: maps (vite dev, babel inline sourcemaps) are decoded by
+  // fetch itself, so they bypass the network-url check
+  if (!isFetchableUrl(sourceMapUrl) && !INLINE_SOURCEMAP_REGEX.test(sourceMapUrl)) {
     return null;
   }
 
@@ -356,6 +390,7 @@ export const symbolicateStack = async (
         fileName: symbolicatedSource.fileName,
         lineNumber: symbolicatedSource.lineNumber,
         columnNumber: symbolicatedSource.columnNumber,
+        isIgnoreListed: symbolicatedSource.isIgnoreListed,
         isSymbolicated: true,
       };
     }),

package/src/types.ts

@@ -298,6 +298,22 @@ export interface Family {
   current: unknown;
 }
 
+/**
+ * React 19 flight metadata for a server component owner (ReactComponentInfo).
+ * Unlike client owners it has no `tag`; the owner chain continues via `owner`.
+ */
+export interface ServerComponentInfo {
+  name?: string;
+  env?: string;
+  owner?: Fiber | ServerComponentInfo | null;
+  debugStack?: Error | null;
+}
+
+export interface RendererRefreshUpdate {
+  staleFamilies: Set<Family>;
+  updatedFamilies: Set<Family>;
+}
+
 /**
  * Represents a react-internal Fiber node.
  */
@@ -367,6 +383,9 @@ export interface ReactDevToolsGlobalHook {
   onCommitFiberRoot: (rendererID: number, root: FiberRoot, priority: number | void) => void;
   onCommitFiberUnmount: (rendererID: number, fiber: Fiber) => void;
   onPostCommitFiberRoot: (rendererID: number, root: FiberRoot) => void;
+  // called by dev builds of react-reconciler on root schedule; absent from
+  // the hook react-refresh installs, so it stays optional
+  onScheduleFiberRoot?: (rendererID: number, root: FiberRoot, children: ReactNode) => void;
   renderers: Map<number, ReactRenderer>;
   supportsFiber: boolean;
 
@@ -402,13 +421,7 @@ export interface ReactRenderer {
   reconcilerVersion: string;
   rendererPackageName: string;
   // react refresh
-  scheduleRefresh?: (
-    root: FiberRoot,
-    update: {
-      staleFamilies: Set<Family>;
-      updatedFamilies: Set<Family>;
-    },
-  ) => void;
+  scheduleRefresh?: (root: FiberRoot, update: RendererRefreshUpdate) => void;
   scheduleRoot?: (root: FiberRoot, element: React.ReactNode) => void;
   scheduleUpdate?: (fiber: Fiber) => void;
 

package/src/unsubscribe.ts

@@ -0,0 +1,17 @@
+export interface Unsubscribe extends Disposable {
+  (): void;
+}
+
+/**
+ * Wraps a teardown callback so it is both callable and a `Disposable`,
+ * letting subscriptions compose through explicit resource management:
+ *
+ * @example
+ * ```ts
+ * using instrumentation = instrument({ onCommitFiberRoot });
+ * using refresh = instrumentReactRefresh({ onRefresh: handleRefresh });
+ * // both torn down automatically at scope exit
+ * ```
+ */
+export const toUnsubscribe = (dispose: () => void): Unsubscribe =>
+  Object.assign(dispose, { [Symbol.dispose]: dispose });