@logbrew/sdk 0.1.17 → 0.1.18

package/issue-stack.cjs

@@ -5,6 +5,7 @@ const MAX_ISSUE_STACK_FUNCTION_LENGTH = 256;
 const MAX_ISSUE_STACK_MODULE_LENGTH = 512;
 const SAFE_DEBUG_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
 const LOCAL_ABSOLUTE_PATH_PATTERN = /(?:^|\s)(?:\/(?:Users|home|private|tmp|var|Volumes)\/|[A-Za-z]:[\\/])/u;
+const DEBUG_ID_REGISTRY = Symbol.for("logbrew.release-artifact.debug-ids");
 
 function buildIssueStackHelpers({ SdkError }) {
   function javascriptStackEvidence(stack, debugIdMap) {
@@ -181,24 +182,52 @@ function sanitizeFrameFilename(value) {
 }
 
 function debugIdForFrame(filename, debugIdMap, SdkError) {
-  if (debugIdMap === undefined || debugIdMap === null) {
-    return null;
-  }
-  if (!debugIdMap || Array.isArray(debugIdMap) || typeof debugIdMap !== "object") {
+  if (debugIdMap !== undefined && debugIdMap !== null
+    && (!debugIdMap || Array.isArray(debugIdMap) || typeof debugIdMap !== "object")) {
     throw new SdkError("validation_error", "debugIdMap must be an object");
   }
+  return debugIdFromEntries(filename, debugIdMap ? Object.entries(debugIdMap) : [])
+    ?? debugIdFromEntries(filename, runtimeDebugIdEntries());
+}
+
+function debugIdFromEntries(filename, entries) {
   const normalizedFilename = sanitizeFrameFilename(filename);
-  const aliases = new Set([normalizedFilename, basename(normalizedFilename)].filter(Boolean));
-  for (const [candidate, debugId] of Object.entries(debugIdMap)) {
+  const frameBasename = basename(normalizedFilename);
+  let basenameMatch = null;
+  for (const [candidate, debugId] of entries) {
     if (typeof debugId !== "string" || !SAFE_DEBUG_ID_PATTERN.test(debugId.trim())) {
       continue;
     }
     const normalizedCandidate = sanitizeFrameFilename(candidate);
-    if (aliases.has(normalizedCandidate) || aliases.has(basename(normalizedCandidate))) {
-      return debugId.trim().toLowerCase();
+    const normalizedDebugId = debugId.trim().toLowerCase();
+    if (normalizedFilename === normalizedCandidate
+      || (normalizedCandidate.includes("/")
+        && normalizedFilename.endsWith(`/${normalizedCandidate.replace(/^\/+/, "")}`))) {
+      return normalizedDebugId;
+    }
+    if (frameBasename === basename(normalizedCandidate)) {
+      basenameMatch = basenameMatch === null || basenameMatch === normalizedDebugId
+        ? normalizedDebugId
+        : false;
+    }
+  }
+  return typeof basenameMatch === "string" ? basenameMatch : null;
+}
+
+function runtimeDebugIdEntries() {
+  try {
+    const registry = typeof globalThis === "object"
+      ? Object.getOwnPropertyDescriptor(globalThis, DEBUG_ID_REGISTRY)?.value
+      : null;
+    if (!registry || Array.isArray(registry) || typeof registry !== "object") {
+      return [];
     }
+    return Object.entries(Object.getOwnPropertyDescriptors(registry)).slice(0, 512).flatMap(
+      ([candidate, descriptor]) => "value" in descriptor ? [[candidate, descriptor.value]] : []
+    );
+  } catch {
+    return [];
   }
-  return null;
 }
 
 function basename(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logbrew/sdk",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Public LogBrew JavaScript SDK for building, validating, and flushing event batches.",
   "type": "module",
   "main": "./index.cjs",

package/release-artifacts-common.js

@@ -3,6 +3,45 @@ import fs from "node:fs";
 import path from "node:path";
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+export const SOURCE_MAP_DEBUG_ID_KEYS = ["debug_id", "debugId", "debugID", "x_debug_id"];
+
+export function parseOptions(args, spec) {
+  const options = {};
+  const positionals = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    const name = arg.slice(2);
+    const kind = spec[name];
+    if (!kind) {
+      throw new Error(`unknown option: --${name}`);
+    }
+    if (kind === "boolean") {
+      options[name] = true;
+      continue;
+    }
+    const value = args[++index];
+    if (value === undefined || value.startsWith("--")) {
+      throw new Error(`missing value for --${name}`);
+    }
+    options[name] = kind === "repeat" ? [...(options[name] ?? []), value] : value;
+  }
+  if (positionals.length > 0) {
+    throw new Error(`unexpected positional argument: ${positionals[0]}`);
+  }
+  return options;
+}
+
+export function requireOption(options, name) {
+  const value = options[name];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`--${name} is required`);
+  }
+  return value.trim();
+}
 
 export function sortJson(value) {
   if (Array.isArray(value)) {
@@ -22,6 +61,24 @@ export function stableJson(value) {
   return JSON.stringify(sortJson(value));
 }
 
+export function fileReference(value) {
+  return value.split("?", 1)[0].split("#", 1)[0];
+}
+
+export function relativeTo(root, filePath) {
+  return path.relative(root, filePath).split(path.sep).join("/");
+}
+
+export function sourceMapDebugId(payload) {
+  for (const key of SOURCE_MAP_DEBUG_ID_KEYS) {
+    const value = payload[key];
+    if (typeof value === "string" && value.trim() !== "") {
+      return value.trim();
+    }
+  }
+  return null;
+}
+
 export function printJson(payload) {
   process.stdout.write(`${JSON.stringify(sortJson(payload), null, 2)}\n`);
 }

package/release-artifacts-symbolication.js

@@ -1,58 +1,19 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import {
+  fileReference,
+  readJsonObject,
+  relativeTo,
+  safeResolve,
+  sourceMapDebugId
+} from "./release-artifacts-common.js";
+
 const SCRIPT_VERSION = "0.1.0";
 const MAX_SOURCE_CONTEXT_FILE_BYTES = 1024 * 1024;
-const SOURCE_MAP_DEBUG_ID_KEYS = ["debug_id", "debugId", "debugID", "x_debug_id"];
 const VLQ_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 const VLQ_VALUES = new Map([...VLQ_CHARS].map((char, index) => [char, index]));
 
-function fileReference(value) {
-  return value.split("?", 1)[0].split("#", 1)[0];
-}
-
-function toPosix(value) {
-  return value.split(path.sep).join("/");
-}
-
-function relativeTo(root, filePath) {
-  return toPosix(path.relative(root, filePath));
-}
-
-function safeResolve(candidate, root) {
-  const resolvedRoot = fs.realpathSync(root);
-  const resolved = path.resolve(candidate);
-  const comparable = fs.existsSync(resolved) ? fs.realpathSync(resolved) : resolved;
-  const relative = path.relative(resolvedRoot, comparable);
-  if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) {
-    return comparable;
-  }
-  return null;
-}
-
-function readJsonObject(filePath, label) {
-  let payload;
-  try {
-    payload = JSON.parse(fs.readFileSync(filePath, "utf8"));
-  } catch (error) {
-    throw new Error(`${label} is not valid JSON: ${error.message}`, { cause: error });
-  }
-  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
-    throw new Error(`${label} must be a JSON object`);
-  }
-  return payload;
-}
-
-function sourceMapDebugId(payload) {
-  for (const key of SOURCE_MAP_DEBUG_ID_KEYS) {
-    const value = payload[key];
-    if (typeof value === "string" && value.trim() !== "") {
-      return value.trim();
-    }
-  }
-  return null;
-}
-
 function parseStackFrame(stackFrame) {
   let line = stackFrame.trim();
   if (line.startsWith("at ")) {
@@ -122,7 +83,7 @@ function requireReadyArtifacts(manifest) {
   if (manifest.artifactType !== "javascript_source_map_manifest") {
     throw new Error("only javascript_source_map_manifest symbolication proof is supported");
   }
-  if (!manifest.validation || manifest.validation.status !== "ready") {
+  if (manifest.validation?.status !== "ready") {
     throw new Error("manifest validation status must be ready");
   }
   if (!Array.isArray(manifest.artifacts) || manifest.artifacts.length === 0) {
@@ -132,7 +93,7 @@ function requireReadyArtifacts(manifest) {
     if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)) {
       throw new Error("artifact entries must be JSON objects");
     }
-    if (!artifact.validation || artifact.validation.status !== "ready") {
+    if (artifact.validation?.status !== "ready") {
       throw new Error("all artifact validation statuses must be ready");
     }
   }

package/release-artifacts-upload.js

@@ -9,8 +9,10 @@ import path from "node:path";
 import {
   byteSize,
   normalizeProjectId,
+  parseOptions,
   printJson,
   readJsonObject,
+  requireOption,
   requireBuildDir,
   safeResolve,
   sha256File,
@@ -23,56 +25,6 @@ const NON_RETRYABLE_UPLOAD_STATUSES = new Set([400, 401, 403, 413]);
 const RETRYABLE_UPLOAD_STATUSES = new Set([408, 429]);
 const SCRIPT_VERSION = "0.1.0";
 
-function parseOptions(args) {
-  const spec = {
-    "build-dir": "string",
-    manifest: "string",
-    endpoint: "string",
-    "token-env": "string",
-    "dry-run": "boolean",
-    "allow-hosted": "boolean",
-    "max-retries": "string",
-    "retry-delay": "string",
-    timeout: "string"
-  };
-  const options = {};
-  const positionals = [];
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (!arg.startsWith("--")) {
-      positionals.push(arg);
-      continue;
-    }
-    const name = arg.slice(2);
-    const kind = spec[name];
-    if (!kind) {
-      throw new Error(`unknown option: --${name}`);
-    }
-    if (kind === "boolean") {
-      options[name] = true;
-      continue;
-    }
-    const value = args[index + 1];
-    if (value === undefined || value.startsWith("--")) {
-      throw new Error(`missing value for --${name}`);
-    }
-    options[name] = value;
-    index += 1;
-  }
-  if (positionals.length > 0) {
-    throw new Error(`unexpected positional argument: ${positionals[0]}`);
-  }
-  return options;
-}
-
-function requireOption(options, name) {
-  const value = options[name];
-  if (typeof value !== "string" || value.trim() === "") {
-    throw new Error(`--${name} is required`);
-  }
-  return value.trim();
-}
-
 function parseNonNegativeInteger(value, label) {
   const trimmed = value.trim();
   if (!/^\d+$/u.test(trimmed)) {
@@ -238,7 +190,7 @@ function requireReadyJavaScriptManifest(manifest, requireProjectId) {
   if (manifest.artifactType !== "javascript_source_map_manifest") {
     throw new Error("only javascript_source_map_manifest uploads are supported by this verifier");
   }
-  if (!manifest.validation || manifest.validation.status !== "ready") {
+  if (manifest.validation?.status !== "ready") {
     throw new Error("manifest validation status must be ready before upload");
   }
   if (!Array.isArray(manifest.artifacts) || manifest.artifacts.length === 0) {
@@ -320,7 +272,17 @@ function exitCodeForUploadStatus(status) {
 }
 
 export async function runUploadJs(args) {
-  const options = parseOptions(args);
+  const options = parseOptions(args, {
+    "build-dir": "string",
+    manifest: "string",
+    endpoint: "string",
+    "token-env": "string",
+    "dry-run": "boolean",
+    "allow-hosted": "boolean",
+    "max-retries": "string",
+    "retry-delay": "string",
+    timeout: "string"
+  });
   try {
     const endpoint = requireOption(options, "endpoint");
     const parsedEndpoint = requireUploadEndpoint(endpoint, Boolean(options["allow-hosted"]));

package/release-artifacts.js

@@ -6,12 +6,18 @@ import path from "node:path";
 
 import {
   byteSize,
+  fileReference,
   normalizeProjectId,
+  parseOptions,
   printJson,
   readJsonObject,
+  relativeTo,
+  requireOption,
   requireBuildDir,
   safeResolve,
   sha256File,
+  sourceMapDebugId,
+  SOURCE_MAP_DEBUG_ID_KEYS,
   sortJson,
   stableJson
 } from "./release-artifacts-common.js";
@@ -20,9 +26,11 @@ import { verifyJavaScriptIssueSymbolication, verifyJavaScriptSymbolication } fro
 
 const DEBUG_ID_NAMESPACE = "16f4a837-7e0b-4d7c-97d9-8a7af1fd2768";
 const DEBUG_ID_RE = /(?:\/\/#|\/\*#)\s*debugId=([A-Za-z0-9._:-]+)/giu;
+const DEBUG_ID_REGISTRY_NAME = "logbrew.release-artifact.debug-ids";
+const DEBUG_ID_REGISTRY_EXPRESSION = `Symbol.for(${JSON.stringify(DEBUG_ID_REGISTRY_NAME)})`;
+const RUNTIME_DEBUG_ID_MARKER = "/*logbrew-runtime-debug-id*/";
 const MINIFIED_SOURCE_SUFFIXES = [".js", ".mjs", ".bundle", ".jsbundle"];
 const SCRIPT_VERSION = "0.1.0";
-const SOURCE_MAP_DEBUG_ID_KEYS = ["debug_id", "debugId", "debugID", "x_debug_id"];
 const SOURCE_MAPPING_COMMENT_RE = /(?:\/\/#|\/\*#)\s*sourceMappingURL=[^\r\n]*/giu;
 const SOURCE_MAPPING_RE = /(?:\/\/#|\/\*#)\s*sourceMappingURL=([^\s*]+)/iu;
 
@@ -39,49 +47,6 @@ function usage() {
   ].join("\n");
 }
 
-function parseOptions(args, spec) {
-  const options = {};
-  const positionals = [];
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (!arg.startsWith("--")) {
-      positionals.push(arg);
-      continue;
-    }
-    const name = arg.slice(2);
-    const kind = spec[name];
-    if (!kind) {
-      throw new Error(`unknown option: --${name}`);
-    }
-    if (kind === "boolean") {
-      options[name] = true;
-      continue;
-    }
-    const value = args[index + 1];
-    if (value === undefined || value.startsWith("--")) {
-      throw new Error(`missing value for --${name}`);
-    }
-    index += 1;
-    if (kind === "repeat") {
-      options[name] = [...(options[name] ?? []), value];
-    } else {
-      options[name] = value;
-    }
-  }
-  if (positionals.length > 0) {
-    throw new Error(`unexpected positional argument: ${positionals[0]}`);
-  }
-  return options;
-}
-
-function requireOption(options, name) {
-  const value = options[name];
-  if (typeof value !== "string" || value.trim() === "") {
-    throw new Error(`--${name} is required`);
-  }
-  return value.trim();
-}
-
 function optionalSourceContextOptions(options) {
   const hasSourceRoot = typeof options["source-root"] === "string" && options["source-root"].trim() !== "";
   const hasContextLines = typeof options["context-lines"] === "string" && options["context-lines"].trim() !== "";
@@ -108,14 +73,6 @@ function optionalSourceContextOptions(options) {
   };
 }
 
-function toPosix(value) {
-  return value.split(path.sep).join("/");
-}
-
-function relativeTo(root, filePath) {
-  return toPosix(path.relative(root, filePath));
-}
-
 function readText(filePath) {
   return fs.readFileSync(filePath, "utf8");
 }
@@ -155,20 +112,6 @@ function findSourceMappingUrl(source) {
   return match?.[1]?.trim() ?? null;
 }
 
-function sourceMapDebugId(payload) {
-  for (const key of SOURCE_MAP_DEBUG_ID_KEYS) {
-    const value = payload[key];
-    if (typeof value === "string" && value.trim() !== "") {
-      return value.trim();
-    }
-  }
-  return null;
-}
-
-function fileReference(value) {
-  return value.split("?", 1)[0].split("#", 1)[0];
-}
-
 function resolveSourceMapPath(jsPath, buildDir, sourceMappingUrl) {
   const warnings = [];
   const errors = [];
@@ -262,26 +205,40 @@ function generateDebugId(relativeJsPath, jsSource, sourceMapPayload) {
   return uuidV5(DEBUG_ID_NAMESPACE, digest.digest("hex"));
 }
 
-function sourceWithDebugId(source, debugId) {
-  if (findDebugId(source)) {
-    return source;
+function executableShebang(source) {
+  return source.startsWith("#!") ? source.match(/^#![^\r\n]*(?:\r?\n|$)/u)?.[0] ?? "" : "";
+}
+
+function sourceStartsWithDirective(source, shebang) {
+  const body = source.slice(shebang.length).replace(/^(?:\s|\/\/[^\r\n]*(?:\r?\n|$)|\/\*[\s\S]*?\*\/)+/u, "");
+  return body.startsWith("\"") || body.startsWith("'");
+}
+
+function sourceWithDebugId(source, debugId, relativePath) {
+  const registryLine = `;try{${RUNTIME_DEBUG_ID_MARKER}(function(){var g=globalThis,s=${DEBUG_ID_REGISTRY_EXPRESSION},r=g[s];if(!r||typeof r!=="object")r=g[s]=Object.create(null);r[${JSON.stringify(relativePath)}]=${JSON.stringify(debugId)}})()}catch(_){}\n`;
+  const shebang = executableShebang(source);
+  const prepared = source.includes(RUNTIME_DEBUG_ID_MARKER)
+    ? source
+    : `${shebang}${shebang === source && shebang ? "\n" : ""}${registryLine}${source.slice(shebang.length)}`;
+  if (findDebugId(prepared)) {
+    return prepared;
   }
   const debugLine = `//# debugId=${debugId}\n`;
-  const matches = [...source.matchAll(SOURCE_MAPPING_COMMENT_RE)];
+  const matches = [...prepared.matchAll(SOURCE_MAPPING_COMMENT_RE)];
   if (matches.length === 0) {
-    return `${source}${source.endsWith("\n") ? "" : "\n"}${debugLine}`;
+    return `${prepared}${prepared.endsWith("\n") ? "" : "\n"}${debugLine}`;
   }
   const last = matches.at(-1);
-  const prefix = source.slice(0, last.index);
+  const prefix = prepared.slice(0, last.index);
   const separator = prefix.endsWith("\n") || prefix.endsWith("\r") ? "" : "\n";
-  return `${prefix}${separator}${debugLine}${source.slice(last.index)}`;
+  return `${prefix}${separator}${debugLine}${prepared.slice(last.index)}`;
 }
 
 function normalizeSourcePrefixes(values) {
   const prefixes = [];
   for (const value of values ?? []) {
     for (const candidate of [path.resolve(value), fs.existsSync(value) ? fs.realpathSync(value) : path.resolve(value)]) {
-      const normalized = toPosix(candidate).replace(/\/+$/u, "");
+      const normalized = candidate.split(path.sep).join("/").replace(/\/+$/u, "");
       if (normalized && !prefixes.includes(normalized)) {
         prefixes.push(normalized);
       }
@@ -317,30 +274,27 @@ function sourceMapPayloadForDebugId(payload, { stripSourcesContent, sourcePrefix
   if (!stripSourcesContent && !updatedSources) {
     return payload;
   }
-  const updated = { ...payload };
+  const updated = updatedSources ? { ...payload, sources: updatedSources } : { ...payload };
   if (stripSourcesContent) {
     delete updated.sourcesContent;
   }
-  if (updatedSources) {
-    updated.sources = updatedSources;
-  }
   return updated;
 }
 
-function sourceMapWithPrivacyUpdates(payload, debugId, { stripSourcesContent, sourcePrefixes }) {
-  const updatedSources = sourceMapSourcesWithoutPrefixes(payload, sourcePrefixes);
-  if (sourceMapDebugId(payload) && (!stripSourcesContent || !("sourcesContent" in payload)) && !updatedSources) {
+function sourceMapWithPrivacyUpdates(payload, debugId, options) {
+  const privacyUpdated = sourceMapPayloadForDebugId(payload, options);
+  const { shiftGeneratedLines } = options;
+  if (sourceMapDebugId(payload)
+    && privacyUpdated === payload
+    && !shiftGeneratedLines) {
     return payload;
   }
-  const updated = { ...payload };
+  const updated = { ...privacyUpdated };
   if (!sourceMapDebugId(updated)) {
     updated.debug_id = debugId;
   }
-  if (stripSourcesContent) {
-    delete updated.sourcesContent;
-  }
-  if (updatedSources) {
-    updated.sources = updatedSources;
+  if (shiftGeneratedLines && typeof updated.mappings === "string") {
+    updated.mappings = `;${updated.mappings}`;
   }
   return updated;
 }
@@ -416,7 +370,19 @@ function buildArtifactPlan(jsPath, buildDir, options) {
   } = inspectArtifactFiles(jsPath, buildDir);
   const changes = [];
   let debugId = jsDebugId || mapDebugId;
+  const needsRuntimeDebugId = !jsSource.includes(RUNTIME_DEBUG_ID_MARKER);
+  if (needsRuntimeDebugId && sourceStartsWithDirective(jsSource, executableShebang(jsSource))) {
+    errors.push("runtime Debug ID injection cannot precede a script directive");
+  }
+  if (needsRuntimeDebugId
+    && sourceMapPayload
+    && (typeof sourceMapPayload.mappings !== "string" || sourceMapPayload.mappings === "")) {
+    errors.push("source map mappings must be a non-empty string before runtime Debug ID injection");
+  }
   if (errors.length === 0 && sourceMapPayload) {
+    if (needsRuntimeDebugId) {
+      changes.push("minifiedSource.runtimeDebugId");
+    }
     if (!debugId) {
       debugId = generateDebugId(
         relJs,
@@ -458,7 +424,8 @@ function applyArtifactPlan(artifact, buildDir, options) {
   const jsPath = path.join(buildDir, artifact.path);
   const sourceMapPath = path.join(buildDir, artifact.sourceMapPath);
   const jsSource = readText(jsPath);
-  const updatedSource = sourceWithDebugId(jsSource, debugId);
+  const shiftGeneratedLines = !jsSource.includes(RUNTIME_DEBUG_ID_MARKER);
+  const updatedSource = sourceWithDebugId(jsSource, debugId, artifact.path);
   if (updatedSource !== jsSource) {
     writeText(jsPath, updatedSource);
   }
@@ -466,7 +433,10 @@ function applyArtifactPlan(artifact, buildDir, options) {
   if (!payload || errors.length > 0) {
     throw new Error(`${artifact.path}: source map became unreadable before write`);
   }
-  const updatedPayload = sourceMapWithPrivacyUpdates(payload, debugId, options);
+  const updatedPayload = sourceMapWithPrivacyUpdates(payload, debugId, {
+    ...options,
+    shiftGeneratedLines
+  });
   if (stableJson(updatedPayload) !== stableJson(payload)) {
     writeText(sourceMapPath, `${JSON.stringify(sortJson(updatedPayload), null, 2)}\n`);
   }