refactor(@angular/build): centralize sourcemap buffer slicing and removal

clydin · clydin · commit d51b258bb36f · 2026-08-11T09:47:19.000-04:00
Extract and centralize trailing sourcemap comment inspection, extraction, and buffer slicing into the shared source-map utility module. Previously, buffer scanning and removal logic was duplicated between the main-thread transformer fast path and the worker script.

The `removeSourceMappingURL` function is overloaded to accept both `string` and `Uint8Array` / `Buffer` inputs natively. When given raw byte buffers, it uses a zero-copy fast path to strip single trailing sourcemap comments directly from the buffer without decoding into a JavaScript string, falling back to the state-machine parser only when multiple or non-trailing comments are present.
diff --git a/packages/angular/build/src/tools/esbuild/javascript-transformer-worker.ts b/packages/angular/build/src/tools/esbuild/javascript-transformer-worker.ts
@@ -12,6 +12,7 @@ import { createRequire } from 'node:module';
 import Piscina from 'piscina';
 import { useBabelLinker } from '../../utils/environment-options.js';
 import {
+  findTrailingSourceMapComment,
   isTrailingSourceMapComment,
   loadInputSourceMap,
   loadInputSourceMapFromUrl,
@@ -37,7 +38,6 @@ interface TransformOptions extends Omit<JavaScriptTransformRequest, 'filename' |
 
 const textDecoder = new TextDecoder();
 const textEncoder = new TextEncoder();
-const SOURCEMAP_COMMENT_BYTES = Buffer.from('//# sourceMappingURL=');
 
 async function instrumentCoverage(
   filename: string,
@@ -97,54 +97,34 @@ export default async function transformJavaScript(
   let isAlreadyStripped = false;
 
   if (typeof data !== 'string') {
-    const dataBuffer = Buffer.isBuffer(data)
-      ? data
-      : Buffer.from(data.buffer, data.byteOffset, data.byteLength);
-
-    const firstIndex = dataBuffer.indexOf(SOURCEMAP_COMMENT_BYTES);
-    if (firstIndex === -1) {
+    const trailing = findTrailingSourceMapComment(data);
+    if (trailing === null) {
       // 0 comments: fast path, no sourcemap to load or strip
       textData = textDecoder.decode(data);
       isAlreadyStripped = true;
-    } else {
-      const lastIndex = dataBuffer.lastIndexOf(SOURCEMAP_COMMENT_BYTES);
-      // Skip any preceding horizontal whitespace (spaces/tabs) to find the start of the line.
-      let prevIdx = lastIndex - 1;
-      while (prevIdx >= 0 && (dataBuffer[prevIdx] === 32 || dataBuffer[prevIdx] === 9)) {
-        prevIdx--;
-      }
-      // Ensure the comment starts at the beginning of a line or the start of the file,
-      // preventing false positives for occurrences inside inline string literals or code.
-      const isLineStart = prevIdx < 0 || dataBuffer[prevIdx] === 10 || dataBuffer[prevIdx] === 13;
-
-      if (firstIndex === lastIndex && isLineStart) {
-        const urlLine = dataBuffer
-          .subarray(lastIndex + SOURCEMAP_COMMENT_BYTES.length)
-          .toString('utf-8');
-
-        if (useInputSourcemap) {
-          inputSourceMap = loadInputSourceMapFromUrl(filename, urlLine);
-          if (inputSourceMap !== undefined) {
-            // Valid trailing sourcemap comment confirmed: safe to slice code buffer for transformation passes.
-            // Note: If no passes modify the code, the untouched original `data` buffer is returned below.
-            textData = textDecoder.decode(dataBuffer.subarray(0, prevIdx < 0 ? 0 : prevIdx + 1));
-            isAlreadyStripped = true;
-          } else {
-            // Not a valid trailing sourcemap (e.g. inside template literal): fallback to full decode
-            textData = textDecoder.decode(data);
-          }
-        } else if (isTrailingSourceMapComment(urlLine)) {
-          // Valid trailing sourcemap comment confirmed: safe to slice code buffer
-          textData = textDecoder.decode(dataBuffer.subarray(0, prevIdx < 0 ? 0 : prevIdx + 1));
+    } else if (trailing !== undefined) {
+      if (useInputSourcemap) {
+        inputSourceMap = loadInputSourceMapFromUrl(filename, trailing.urlLine);
+        if (inputSourceMap !== undefined) {
+          // Valid trailing sourcemap comment confirmed: safe to slice code buffer for transformation passes.
+          // Note: If no passes modify the code, the untouched original `data` buffer is returned below.
+          textData = textDecoder.decode(trailing.code);
           isAlreadyStripped = true;
         } else {
-          // Fallback to full decode and state-machine stripping
+          // Not a valid trailing sourcemap (e.g. inside template literal): fallback to full decode
           textData = textDecoder.decode(data);
         }
+      } else if (isTrailingSourceMapComment(trailing.urlLine)) {
+        // Valid trailing sourcemap comment confirmed: safe to slice code buffer
+        textData = textDecoder.decode(trailing.code);
+        isAlreadyStripped = true;
       } else {
-        // Multiple comments or comment not at line start: fall back to full decode and string parser
+        // Fallback to full decode and state-machine stripping
         textData = textDecoder.decode(data);
       }
+    } else {
+      // Multiple comments or comment not at line start: fall back to full decode and string parser
+      textData = textDecoder.decode(data);
     }
   } else {
     textData = data;
diff --git a/packages/angular/build/src/tools/esbuild/javascript-transformer.ts b/packages/angular/build/src/tools/esbuild/javascript-transformer.ts
@@ -13,7 +13,6 @@ import { removeSourceMappingURL } from '../../utils/source-map';
 import { WorkerPool, WorkerPoolOptions } from '../../utils/worker-pool';
 import { Cache } from './cache';
 
-const SOURCEMAP_COMMENT_BYTES = Buffer.from('sourceMappingURL=');
 const LINKER_DECLARATION_PREFIX = 'ɵɵngDeclare';
 const LINKER_DECLARATION_PREFIX_BYTES = Buffer.from(LINKER_DECLARATION_PREFIX, 'utf-8');
 
@@ -226,27 +225,13 @@ export class JavaScriptTransformer {
         this.#commonOptions.sourcemap &&
         (!!this.#commonOptions.thirdPartySourcemaps || !/[\\/]node_modules[\\/]/.test(filename));
 
-      if (typeof data === 'string') {
-        return Buffer.from(keepSourcemap ? data : removeSourceMappingURL(data), 'utf-8');
-      }
-
       if (keepSourcemap) {
-        return data;
-      }
-
-      const dataBuffer = Buffer.isBuffer(data)
-        ? data
-        : Buffer.from(data.buffer, data.byteOffset, data.byteLength);
-
-      // Fast check on raw ASCII bytes to avoid UTF-8 string decoding if no comment exists.
-      if (dataBuffer.indexOf(SOURCEMAP_COMMENT_BYTES) === -1) {
-        return data;
+        return typeof data === 'string' ? Buffer.from(data, 'utf-8') : data;
       }
 
-      const text = dataBuffer.toString('utf-8');
-      const stripped = removeSourceMappingURL(text);
-
-      return stripped === text ? data : Buffer.from(stripped, 'utf-8');
+      return typeof data === 'string'
+        ? Buffer.from(removeSourceMappingURL(data), 'utf-8')
+        : removeSourceMappingURL(data);
     }
 
     // Only standalone (non-pooled) ArrayBuffers can be transferred across worker threads.
diff --git a/packages/angular/build/src/utils/source-map.ts b/packages/angular/build/src/utils/source-map.ts
@@ -11,17 +11,90 @@ import { existsSync, readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+export const SOURCEMAP_COMMENT_PREFIX = '//# sourceMappingURL=';
+export const SOURCEMAP_COMMENT_BYTES = Buffer.from(SOURCEMAP_COMMENT_PREFIX);
+
+/**
+ * Checks for a single trailing `//# sourceMappingURL=` comment on a raw buffer.
+ *
+ * @param data The raw byte buffer to inspect.
+ * @returns An object containing the sliced code buffer and URL snippet if a single trailing comment exists,
+ *          `null` if no sourcemap comment exists in the buffer, or `undefined` if multiple/non-trailing comments exist.
+ */
+export function findTrailingSourceMapComment(
+  data: Uint8Array,
+): { code: Uint8Array; urlLine: string } | null | undefined {
+  const dataBuffer = Buffer.isBuffer(data)
+    ? data
+    : Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+
+  const firstIndex = dataBuffer.indexOf(SOURCEMAP_COMMENT_BYTES);
+  if (firstIndex === -1) {
+    return null;
+  }
+
+  const lastIndex = dataBuffer.lastIndexOf(SOURCEMAP_COMMENT_BYTES);
+  // Skip any preceding horizontal whitespace (spaces/tabs) to find the start of the line.
+  let prevIdx = lastIndex - 1;
+  while (prevIdx >= 0 && (dataBuffer[prevIdx] === 32 || dataBuffer[prevIdx] === 9)) {
+    prevIdx--;
+  }
+  // Ensure the comment starts at the beginning of a line or the start of the file,
+  // preventing false positives for occurrences inside inline string literals or code.
+  const isLineStart = prevIdx < 0 || dataBuffer[prevIdx] === 10 || dataBuffer[prevIdx] === 13;
+
+  if (firstIndex === lastIndex && isLineStart) {
+    const urlLine = dataBuffer
+      .subarray(lastIndex + SOURCEMAP_COMMENT_BYTES.length)
+      .toString('utf-8');
+
+    return {
+      code: dataBuffer.subarray(0, prevIdx < 0 ? 0 : prevIdx + 1),
+      urlLine,
+    };
+  }
+
+  return undefined;
+}
+
 /**
  * Removes `//# sourceMappingURL=` comments safely from the given JavaScript code,
  * ignoring any occurrences that are inside string literals, template literals, or block comments.
  *
- * It uses a lightweight state-machine parser to accurately handle nested template literals.
+ * For raw Uint8Array / Buffer inputs, it optimizes performance by inspecting trailing byte sequences
+ * to slice the buffer directly without full string decoding.
  *
- * @param code The JavaScript source code.
+ * @param code The JavaScript source code as a string or Uint8Array.
  * @returns The code with top-level sourcemap comments removed.
  */
-export function removeSourceMappingURL(code: string): string {
-  if (!code.includes('//# sourceMappingURL=')) {
+export function removeSourceMappingURL(code: string): string;
+export function removeSourceMappingURL(code: Uint8Array): Uint8Array;
+export function removeSourceMappingURL(code: string | Uint8Array): string | Uint8Array {
+  if (typeof code === 'string') {
+    return removeSourceMappingURLFromString(code);
+  }
+
+  const trailing = findTrailingSourceMapComment(code);
+  if (trailing === null) {
+    return code;
+  }
+
+  if (trailing && isTrailingSourceMapComment(trailing.urlLine)) {
+    return trailing.code;
+  }
+
+  // Fallback to full decode and state-machine stripping for multiple comments or non-trailing comments
+  const dataBuffer = Buffer.isBuffer(code)
+    ? code
+    : Buffer.from(code.buffer, code.byteOffset, code.byteLength);
+  const text = dataBuffer.toString('utf-8');
+  const stripped = removeSourceMappingURLFromString(text);
+
+  return stripped === text ? code : Buffer.from(stripped, 'utf-8');
+}
+
+function removeSourceMappingURLFromString(code: string): string {
+  if (!code.includes(SOURCEMAP_COMMENT_PREFIX)) {
     return code;
   }
 
@@ -64,12 +137,12 @@ export function removeSourceMappingURL(code: string): string {
           }
         }
 
-        if (!isEscaped && code.startsWith('//# sourceMappingURL=', i)) {
+        if (!isEscaped && code.startsWith(SOURCEMAP_COMMENT_PREFIX, i)) {
           if (i > lastCopiedIndex) {
             result.push(code.slice(lastCopiedIndex, i));
           }
           // Skip the rest of the comment line up to the newline
-          i += 21;
+          i += SOURCEMAP_COMMENT_PREFIX.length;
           while (i < len && code[i] !== '\n' && code[i] !== '\r') {
             i++;
           }
@@ -308,7 +381,7 @@ export function loadInputSourceMapFromUrl(
 export function loadInputSourceMap(filename: string, code: string): EncodedSourceMap | undefined {
   // Locate the last sourceMappingURL comment using lastIndexOf to avoid scanning
   // the entire file with a regular expression (significant for large files).
-  const lastSourceMapIndex = code.lastIndexOf('//# sourceMappingURL=');
+  const lastSourceMapIndex = code.lastIndexOf(SOURCEMAP_COMMENT_PREFIX);
   if (lastSourceMapIndex === -1) {
     return undefined;
   }
@@ -325,5 +398,8 @@ export function loadInputSourceMap(filename: string, code: string): EncodedSourc
     }
   }
 
-  return loadInputSourceMapFromUrl(filename, code.slice(lastSourceMapIndex + 21));
+  return loadInputSourceMapFromUrl(
+    filename,
+    code.slice(lastSourceMapIndex + SOURCEMAP_COMMENT_PREFIX.length),
+  );
 }
diff --git a/packages/angular/build/src/utils/source-map_spec.ts b/packages/angular/build/src/utils/source-map_spec.ts
@@ -102,6 +102,42 @@ describe('removeSourceMappingURL', () => {
     const code = 'console.log("hello");\r\n//# sourceMappingURL=main.js.map\r\nconst next = 2;';
     expect(removeSourceMappingURL(code)).toBe('console.log("hello");\r\n\r\nconst next = 2;');
   });
+
+  describe('with Uint8Array / Buffer inputs', () => {
+    it('should strip trailing sourcemap comment from Uint8Array buffer', () => {
+      const buffer = Buffer.from(
+        'console.log("hello");\n//# sourceMappingURL=main.js.map',
+        'utf-8',
+      );
+      const result = removeSourceMappingURL(buffer);
+
+      expect(Buffer.from(result).toString('utf-8')).toBe('console.log("hello");\n');
+    });
+
+    it('should return exact input buffer when no sourcemap comment is present', () => {
+      const buffer = Buffer.from('console.log("hello");\nconst x = 1;', 'utf-8');
+      const result = removeSourceMappingURL(buffer);
+
+      expect(result).toBe(buffer);
+    });
+
+    it('should handle multiple sourcemap comments in a buffer via fallback', () => {
+      const buffer = Buffer.from(
+        '//# sourceMappingURL=first.js.map\nconsole.log("mid");\n//# sourceMappingURL=second.js.map',
+        'utf-8',
+      );
+      const result = removeSourceMappingURL(buffer);
+
+      expect(Buffer.from(result).toString('utf-8')).toBe('\nconsole.log("mid");\n');
+    });
+
+    it('should not strip sourcemap comments inside template strings in a buffer', () => {
+      const buffer = Buffer.from('const str = `\n//# sourceMappingURL=inline.js.map\n`;', 'utf-8');
+      const result = removeSourceMappingURL(buffer);
+
+      expect(Buffer.from(result).toString('utf-8')).toBe(buffer.toString('utf-8'));
+    });
+  });
 });
 
 describe('loadInputSourceMapFromUrl', () => {
