@logbrew/sdk 0.1.38 → 0.1.39

package/release-artifacts-common.js

@@ -1,41 +1,145 @@
-import crypto from "node:crypto";
-import fs from "node:fs";
+import { access, readFile, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import path from "node:path";
+import { promisify } from "node:util";
+import { realpath } from "node:fs";
+
+/**
+ * @typedef {"boolean" | "repeat" | "string"} OptionKind
+ * @typedef {string | true | readonly string[]} OptionValue
+ * @typedef {Readonly<Record<string, OptionValue>>} CliOptions
+ * @typedef {Readonly<Record<string, OptionKind>>} OptionSpec
+ * @typedef {Readonly<Record<string, unknown>>} JsonObject
+ * @typedef {{ readonly positional: string, readonly width: number }} PositionalToken
+ * @typedef {{ readonly kind: OptionKind, readonly name: string, readonly value: string | true, readonly width: number }} OptionToken
+ */
 
 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"];
+const SOURCE_MAP_DEBUG_ID_KEYS = ["debug_id", "debugId", "debugID", "x_debug_id"];
+const OPTION_PREFIX = "--";
+const FLAG_WIDTH = 1;
+const VALUE_OPTION_WIDTH = 2;
+const NO_POSITIONALS = 0;
+const FIRST_PART_ONLY = 1;
+const JSON_INDENT = 2;
+const realPathOf = promisify(realpath);
+
+/**
+ * @param {unknown} value
+ * @returns {value is JsonObject}
+ */
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is readonly unknown[]}
+ */
+function isJsonList(value) {
+  return Array.isArray(value);
+}
+
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 
-export function parseOptions(args, spec) {
+/**
+ * @param {OptionSpec} spec
+ * @param {string} name
+ * @returns {OptionKind}
+ */
+function optionKind(spec, name) {
+  const kind = spec[name];
+  if (kind === undefined) {
+    throw new Error(`unknown option: --${name}`);
+  }
+  return kind;
+}
+
+/**
+ * @param {readonly string[]} window
+ * @param {OptionSpec} spec
+ * @returns {OptionToken | PositionalToken}
+ */
+function readToken(window, spec) {
+  const [arg = "", value] = window;
+  if (!arg.startsWith(OPTION_PREFIX)) {
+    return { positional: arg, width: FLAG_WIDTH };
+  }
+  const name = arg.slice(OPTION_PREFIX.length);
+  const kind = optionKind(spec, name);
+  if (kind === "boolean") {
+    return { kind, name, value: true, width: FLAG_WIDTH };
+  }
+  if (value === undefined || value.startsWith(OPTION_PREFIX)) {
+    throw new Error(`missing value for --${name}`);
+  }
+  return { kind, name, value, width: VALUE_OPTION_WIDTH };
+}
+
+/**
+ * @param {readonly string[]} args
+ * @param {OptionSpec} spec
+ * @returns {readonly (OptionToken | PositionalToken)[]}
+ */
+function readTokens(args, spec) {
+  /** @type {(OptionToken | PositionalToken)[]} */
+  const tokens = [];
+  let index = 0;
+  while (index < args.length) {
+    const token = readToken(args.slice(index, index + VALUE_OPTION_WIDTH), spec);
+    tokens.push(token);
+    index += token.width;
+  }
+  return tokens;
+}
+
+/**
+ * @param {OptionValue | undefined} previous
+ * @param {OptionToken} token
+ * @returns {OptionValue}
+ */
+function optionValue(previous, token) {
+  if (token.kind !== "repeat" || token.value === true) {
+    return token.value;
+  }
+  /** @type {readonly string[]} */
+  const earlier = typeof previous === "object" ? previous : [];
+  return [...earlier, token.value];
+}
+
+/**
+ * @param {readonly string[]} args
+ * @param {OptionSpec} spec
+ * @returns {CliOptions}
+ */
+function parseOptions(args, spec) {
+  const tokens = readTokens(args, spec);
+  const positionals = tokens.filter((token) => "positional" in token);
+  if (positionals.length > NO_POSITIONALS) {
+    throw new Error(`unexpected positional argument: ${String(positionals[NO_POSITIONALS]?.positional)}`);
+  }
+  /** @type {Record<string, OptionValue>} */
   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}`);
+  for (const token of tokens) {
+    if ("name" in token) {
+      options[token.name] = optionValue(options[token.name], token);
     }
-    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) {
+/**
+ * @param {CliOptions} options
+ * @param {string} name
+ * @returns {string}
+ */
+function requireOption(options, name) {
   const value = options[name];
   if (typeof value !== "string" || value.trim() === "") {
     throw new Error(`--${name} is required`);
@@ -43,97 +147,274 @@ export function requireOption(options, name) {
   return value.trim();
 }
 
-export function sortJson(value) {
-  if (Array.isArray(value)) {
-    return value.map(sortJson);
+/**
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function sortJson(value) {
+  if (isJsonList(value)) {
+    return value.map((item) => sortJson(item));
   }
-  if (value && typeof value === "object") {
-    return Object.fromEntries(
-      Object.keys(value)
-        .sort()
-        .map((key) => [key, sortJson(value[key])])
-    );
+  if (isJsonObject(value)) {
+    const keys = Object.keys(value);
+    keys.sort();
+    return Object.fromEntries(keys.map((key) => [key, sortJson(value[key])]));
   }
   return value;
 }
 
-export function stableJson(value) {
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function stableJson(value) {
   return JSON.stringify(sortJson(value));
 }
 
-export function fileReference(value) {
-  return value.split("?", 1)[0].split("#", 1)[0];
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function fileReference(value) {
+  const [withoutQuery = ""] = value.split("?", FIRST_PART_ONLY);
+  const [withoutFragment = ""] = withoutQuery.split("#", FIRST_PART_ONLY);
+  return withoutFragment;
 }
 
-export function relativeTo(root, filePath) {
+/**
+ * @param {string} root
+ * @param {string} filePath
+ * @returns {string}
+ */
+function relativeTo(root, filePath) {
   return path.relative(root, filePath).split(path.sep).join("/");
 }
 
-export function sourceMapDebugId(payload) {
+/**
+ * @param {JsonObject} payload
+ * @returns {string | undefined}
+ */
+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;
+  return undefined;
+}
+
+/**
+ * @param {unknown} payload
+ * @returns {void}
+ */
+function printJson(payload) {
+  process.stdout.write(`${JSON.stringify(sortJson(payload), undefined, JSON_INDENT)}\n`);
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<boolean>}
+ */
+async function pathExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<string>}
+ */
+async function realPath(filePath) {
+  return realPathOf(filePath);
 }
 
-export function printJson(payload) {
-  process.stdout.write(`${JSON.stringify(sortJson(payload), null, 2)}\n`);
+/**
+ * @param {string} filePath
+ * @returns {Promise<string>}
+ */
+async function readText(filePath) {
+  return readFile(filePath, "utf8");
 }
 
-export function safeResolve(candidate, root) {
-  const resolvedRoot = fs.realpathSync(root);
+/**
+ * @param {string} candidate
+ * @param {string} root
+ * @returns {Promise<string | undefined>}
+ */
+async function safeResolve(candidate, root) {
+  const resolvedRoot = await realPath(root);
   const resolved = path.resolve(candidate);
-  const comparable = fs.existsSync(resolved) ? fs.realpathSync(resolved) : resolved;
+  const comparable = (await pathExists(resolved)) ? await realPath(resolved) : resolved;
   const relative = path.relative(resolvedRoot, comparable);
   if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) {
     return comparable;
   }
-  return null;
+  return undefined;
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<number>}
+ */
+async function byteSize(filePath) {
+  const stats = await stat(filePath);
+  return stats.size;
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<boolean>}
+ */
+async function isFile(filePath) {
+  const stats = await stat(filePath);
+  return stats.isFile();
 }
 
-export function byteSize(filePath) {
-  return fs.statSync(filePath).size;
+/**
+ * @param {string} filePath
+ * @returns {Promise<boolean>}
+ */
+async function isDirectory(filePath) {
+  const stats = await stat(filePath);
+  return stats.isDirectory();
 }
 
-export function sha256File(filePath) {
-  const digest = crypto.createHash("sha256");
-  digest.update(fs.readFileSync(filePath));
+/**
+ * @param {string} filePath
+ * @returns {Promise<string>}
+ */
+async function sha256File(filePath) {
+  const digest = createHash("sha256");
+  digest.update(await readFile(filePath));
   return digest.digest("hex");
 }
 
-export function requireBuildDir(value) {
+/**
+ * @param {string} value
+ * @returns {Promise<string>}
+ */
+async function requireBuildDir(value) {
   const buildDir = path.resolve(value);
-  if (!fs.existsSync(buildDir) || !fs.statSync(buildDir).isDirectory()) {
+  if (!(await pathExists(buildDir)) || !(await isDirectory(buildDir))) {
     throw new Error(`build directory does not exist: ${value}`);
   }
-  return fs.realpathSync(buildDir);
+  return realPath(buildDir);
 }
 
-export function readJsonObject(filePath, label) {
-  let payload;
+/**
+ * @param {string} filePath
+ * @param {string} label
+ * @returns {Promise<unknown>}
+ */
+async function readJson(filePath, label) {
   try {
-    payload = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    /** @type {unknown} */
+    const payload = JSON.parse(await readText(filePath));
+    return payload;
   } catch (error) {
-    throw new Error(`${label} is not valid JSON: ${error.message}`, { cause: error });
+    throw new Error(`${label} is not valid JSON: ${errorMessage(error)}`, { cause: error });
   }
-  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+}
+
+/**
+ * @param {string} filePath
+ * @param {string} label
+ * @returns {Promise<JsonObject>}
+ */
+async function readJsonObject(filePath, label) {
+  const payload = await readJson(filePath, label);
+  if (!isJsonObject(payload)) {
     throw new Error(`${label} must be a JSON object`);
   }
   return payload;
 }
 
-export function normalizeProjectId(value, errorMessage, required = false) {
+/**
+ * @template Item, Result
+ * @param {readonly Item[]} items
+ * @param {(item: Item) => Promise<Result>} mapper
+ * @returns {Promise<Result[]>}
+ */
+async function mapInOrder(items, mapper) {
+  /** @type {Result[]} */
+  const results = [];
+  /**
+   * @param {readonly Item[]} remaining
+   * @returns {Promise<Result[]>}
+   */
+  async function mapRemaining(remaining) {
+    const [first, ...rest] = remaining;
+    if (remaining.length === NO_POSITIONALS || first === undefined) {
+      return results;
+    }
+    results.push(await mapper(first));
+    return mapRemaining(rest);
+  }
+  return mapRemaining(items);
+}
+
+/**
+ * @template Item
+ * @param {readonly Item[]} items
+ * @param {(item: Item) => Promise<boolean>} predicate
+ * @returns {Promise<Item | undefined>}
+ */
+async function findInOrder(items, predicate) {
+  const [first, ...rest] = items;
+  if (items.length === NO_POSITIONALS || first === undefined) {
+    return undefined;
+  }
+  return (await predicate(first)) ? first : findInOrder(rest, predicate);
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} message
+ * @param {boolean} required
+ * @returns {string | undefined}
+ */
+function normalizeProjectId(value, message, required = false) {
   if (value === undefined || value === null) {
     if (required) {
-      throw new Error(errorMessage);
+      throw new Error(message);
     }
     return undefined;
   }
-  if (typeof value !== "string" || UUID_RE.test(value.trim()) === false) {
-    throw new Error(errorMessage);
+  if (typeof value !== "string" || !UUID_RE.test(value.trim())) {
+    throw new Error(message);
   }
   return value.trim().toLowerCase();
 }
+
+export {
+  SOURCE_MAP_DEBUG_ID_KEYS,
+  byteSize,
+  errorMessage,
+  fileReference,
+  findInOrder,
+  isDirectory,
+  isFile,
+  isJsonList,
+  isJsonObject,
+  mapInOrder,
+  normalizeProjectId,
+  parseOptions,
+  pathExists,
+  printJson,
+  readJsonObject,
+  readText,
+  realPath,
+  relativeTo,
+  requireBuildDir,
+  requireOption,
+  safeResolve,
+  sha256File,
+  sortJson,
+  sourceMapDebugId,
+  stableJson
+};

package/release-artifacts-debug-id.js

@@ -0,0 +1,178 @@
+import { SOURCE_MAP_DEBUG_ID_KEYS, stableJson } from "./release-artifacts-common.js";
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+
+/** @import { JsonObject } from "./release-artifacts-common.js" */
+
+const DEBUG_ID_NAMESPACE = "16f4a837-7e0b-4d7c-97d9-8a7af1fd2768";
+const DEBUG_ID_RE = /(?:\/\/#|\/\*#)\s*debugId=(?<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 HERMES_RUNTIME_DEBUG_ID_RE =
+  /\/\*logbrew-runtime-debug-id\*\/\/\/# debugId=(?<debugId>[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12})/iu;
+const RUNTIME_DEBUG_ID_MARKER = "/*logbrew-runtime-debug-id*/";
+const SOURCE_MAPPING_COMMENT_RE = /(?:\/\/#|\/\*#)\s*sourceMappingURL=[^\r\n]*/giu;
+const SOURCE_MAPPING_RE = /(?:\/\/#|\/\*#)\s*sourceMappingURL=(?<url>[^\s*]+)/iu;
+const SHEBANG_LINE_RE = /^#![^\r\n]*(?:\r?\n|$)/u;
+const LEADING_TRIVIA_RE = /^(?:\s|\/\/[^\r\n]*(?:\r?\n|$)|\/\*[\s\S]*?\*\/)+/u;
+const UUID_BYTE_LENGTH = 16;
+const UUID_TIME_LOW_LENGTH = 8;
+const UUID_SHORT_GROUP_LENGTH = 4;
+const UUID_NODE_LENGTH = 12;
+const UUID_GROUP_LENGTHS = [
+  UUID_TIME_LOW_LENGTH,
+  UUID_SHORT_GROUP_LENGTH,
+  UUID_SHORT_GROUP_LENGTH,
+  UUID_SHORT_GROUP_LENGTH,
+  UUID_NODE_LENGTH
+];
+const UUID_VERSION_BYTE = 6;
+const UUID_VARIANT_BYTE = 8;
+const UUID_VERSION_MODULUS = 16;
+const UUID_VERSION_5_BITS = 80;
+const UUID_VARIANT_MODULUS = 64;
+const UUID_RFC_4122_VARIANT_BITS = 128;
+const UUID_START = 0;
+const LAST_INDEX = -1;
+
+/**
+ * @param {string} source
+ * @returns {string | undefined}
+ */
+function findDebugId(source) {
+  const runtimeDebugId = HERMES_RUNTIME_DEBUG_ID_RE.exec(source)?.groups?.["debugId"];
+  if (runtimeDebugId !== undefined) {
+    return runtimeDebugId;
+  }
+  return [...source.matchAll(DEBUG_ID_RE)].at(LAST_INDEX)?.groups?.["debugId"]?.trim();
+}
+
+/**
+ * @param {string} source
+ * @returns {string | undefined}
+ */
+function findSourceMappingUrl(source) {
+  return SOURCE_MAPPING_RE.exec(source)?.groups?.["url"]?.trim();
+}
+
+/**
+ * @param {string} hex
+ * @returns {string}
+ */
+function formatUuid(hex) {
+  /** @type {string[]} */
+  const groups = [];
+  let offset = UUID_START;
+  for (const length of UUID_GROUP_LENGTHS) {
+    groups.push(hex.slice(offset, offset + length));
+    offset += length;
+  }
+  return groups.join("-");
+}
+
+/**
+ * @param {string} namespace
+ * @param {string} name
+ * @returns {string}
+ */
+function uuidV5(namespace, name) {
+  const bytes = createHash("sha1")
+    .update(Buffer.from(namespace.replaceAll("-", ""), "hex"))
+    .update(Buffer.from(name, "utf8"))
+    .digest()
+    .subarray(UUID_START, UUID_BYTE_LENGTH);
+  bytes.writeUInt8((bytes.readUInt8(UUID_VERSION_BYTE) % UUID_VERSION_MODULUS) + UUID_VERSION_5_BITS, UUID_VERSION_BYTE);
+  bytes.writeUInt8(
+    (bytes.readUInt8(UUID_VARIANT_BYTE) % UUID_VARIANT_MODULUS) + UUID_RFC_4122_VARIANT_BITS,
+    UUID_VARIANT_BYTE
+  );
+  return formatUuid(bytes.toString("hex"));
+}
+
+/**
+ * @param {JsonObject} payload
+ * @returns {string}
+ */
+function canonicalSourceMapWithoutDebugId(payload) {
+  const keys = Object.keys(payload).filter((key) => !SOURCE_MAP_DEBUG_ID_KEYS.includes(key));
+  return stableJson(Object.fromEntries(keys.map((key) => [key, payload[key]])));
+}
+
+/**
+ * @param {string} relativeJsPath
+ * @param {string} jsSource
+ * @param {JsonObject} sourceMapPayload
+ * @returns {string}
+ */
+function generateDebugId(relativeJsPath, jsSource, sourceMapPayload) {
+  const digest = createHash("sha256");
+  digest.update(relativeJsPath);
+  digest.update("\0");
+  digest.update(jsSource.replaceAll(DEBUG_ID_RE, ""));
+  digest.update("\0");
+  digest.update(canonicalSourceMapWithoutDebugId(sourceMapPayload));
+  return uuidV5(DEBUG_ID_NAMESPACE, digest.digest("hex"));
+}
+
+/**
+ * @param {string} source
+ * @returns {string}
+ */
+function executableShebang(source) {
+  return source.startsWith("#!") ? (SHEBANG_LINE_RE.exec(source)?.[UUID_START] ?? "") : "";
+}
+
+/**
+ * @param {string} source
+ * @returns {boolean}
+ */
+function sourceStartsWithDirective(source) {
+  const body = source.slice(executableShebang(source).length).replace(LEADING_TRIVIA_RE, "");
+  return body.startsWith("\"") || body.startsWith("'");
+}
+
+/**
+ * @param {string} source
+ * @param {string} debugId
+ * @param {string} relativePath
+ * @returns {string}
+ */
+function sourceWithRuntimeDebugId(source, debugId, relativePath) {
+  if (source.includes(RUNTIME_DEBUG_ID_MARKER)) {
+    return source;
+  }
+  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 separator = shebang === source && shebang !== "" ? "\n" : "";
+  return `${shebang}${separator}${registryLine}${source.slice(shebang.length)}`;
+}
+
+/**
+ * @param {string} source
+ * @param {string} debugId
+ * @param {string} relativePath
+ * @returns {string}
+ */
+function sourceWithDebugId(source, debugId, relativePath) {
+  const prepared = sourceWithRuntimeDebugId(source, debugId, relativePath);
+  if (findDebugId(prepared) !== undefined) {
+    return prepared;
+  }
+  const debugLine = `//# debugId=${debugId}\n`;
+  const last = [...prepared.matchAll(SOURCE_MAPPING_COMMENT_RE)].at(LAST_INDEX);
+  if (last === undefined) {
+    return `${prepared}${prepared.endsWith("\n") ? "" : "\n"}${debugLine}`;
+  }
+  const prefix = prepared.slice(UUID_START, last.index);
+  const separator = prefix.endsWith("\n") || prefix.endsWith("\r") ? "" : "\n";
+  return `${prefix}${separator}${debugLine}${prepared.slice(last.index)}`;
+}
+
+export {
+  RUNTIME_DEBUG_ID_MARKER,
+  findDebugId,
+  findSourceMappingUrl,
+  generateDebugId,
+  sourceStartsWithDirective,
+  sourceWithDebugId
+};