@logbrew/sdk 0.1.38 → 0.1.39

package/release-artifacts-mappings.js

@@ -0,0 +1,265 @@
+import { fileReference } from "./release-artifacts-common.js";
+import path from "node:path";
+
+/**
+ * @typedef {{ readonly mappings: string, readonly names: unknown, readonly sources: readonly unknown[] }} ValidSourceMap
+ * @typedef {{ readonly column: number, readonly line: number, readonly name?: string, readonly source: string }} OriginalPosition
+ * @typedef {{ readonly shift: number, readonly value: number }} VlqAccumulator
+ * @typedef {{
+ *   readonly generatedColumn: number,
+ *   readonly name: number,
+ *   readonly originalColumn: number,
+ *   readonly originalLine: number,
+ *   readonly source: number
+ * }} DecoderState
+ * @typedef {{
+ *   readonly generatedColumn: number,
+ *   readonly name?: number,
+ *   readonly originalColumn?: number,
+ *   readonly originalLine?: number,
+ *   readonly source?: number
+ * }} MappingSegment
+ */
+
+const VLQ_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const VLQ_VALUES = new Map(Array.from(VLQ_CHARS, (char, index) => [char, index]));
+const VLQ_CONTINUATION = 32;
+const VLQ_SHIFT_STEP = 5;
+const VLQ_SIGN_DIVISOR = 2;
+const INT32_BITS = 32;
+const BINARY_BASE = 2;
+const NO_DELTA = 0;
+const NEGATIVE_SIGN_BIT = 1;
+const ONE_BASED_OFFSET = 1;
+const GENERATED_COLUMN_ONLY = 1;
+const SEGMENT_WITH_NAME = 5;
+const SEGMENT_WITH_SOURCE = 4;
+const SEGMENT_FIELD_COUNTS = new Set([GENERATED_COLUMN_ONLY, SEGMENT_WITH_SOURCE, SEGMENT_WITH_NAME]);
+const NOT_FOUND = -1;
+const LAST = -1;
+const WINDOWS_DRIVE_RE = /^[A-Za-z]:[\\/]/u;
+const INITIAL_STATE = { generatedColumn: NO_DELTA, name: NO_DELTA, originalColumn: NO_DELTA, originalLine: NO_DELTA, source: NO_DELTA };
+const EMPTY_ACCUMULATOR = { shift: NO_DELTA, value: NO_DELTA };
+
+/**
+ * @param {number} value
+ * @returns {number}
+ */
+function toInt32(value) {
+  return Number(BigInt.asIntN(INT32_BITS, BigInt(value)));
+}
+
+/**
+ * @param {number} value
+ * @returns {number}
+ */
+function signedVlqValue(value) {
+  const wrapped = toInt32(value);
+  const magnitude = Math.floor(wrapped / VLQ_SIGN_DIVISOR);
+  return Math.abs(wrapped % VLQ_SIGN_DIVISOR) === NEGATIVE_SIGN_BIT ? -magnitude : magnitude;
+}
+
+/**
+ * @param {string} char
+ * @returns {number}
+ */
+function vlqDigit(char) {
+  const digit = VLQ_VALUES.get(char);
+  if (digit === undefined) {
+    throw new Error("source map mappings contain an invalid base64 VLQ character");
+  }
+  return digit;
+}
+
+/**
+ * @param {VlqAccumulator} accumulator
+ * @param {string} char
+ * @returns {{ readonly decoded: number | undefined, readonly next: VlqAccumulator }}
+ */
+function vlqStep(accumulator, char) {
+  const digit = vlqDigit(char);
+  const value = accumulator.value + toInt32((digit % VLQ_CONTINUATION) * BINARY_BASE ** (accumulator.shift % INT32_BITS));
+  if (digit >= VLQ_CONTINUATION) {
+    return { decoded: undefined, next: { shift: accumulator.shift + VLQ_SHIFT_STEP, value } };
+  }
+  return { decoded: signedVlqValue(value), next: EMPTY_ACCUMULATOR };
+}
+
+/**
+ * @param {VlqAccumulator} accumulator
+ * @returns {void}
+ */
+function requireTerminatedVlq(accumulator) {
+  if (accumulator.shift !== NO_DELTA) {
+    throw new Error("source map mappings contain an unterminated base64 VLQ value");
+  }
+}
+
+/**
+ * @param {string} segment
+ * @returns {number[]}
+ */
+function decodeVlqValues(segment) {
+  /** @type {number[]} */
+  const values = [];
+  /** @type {VlqAccumulator} */
+  let accumulator = EMPTY_ACCUMULATOR;
+  for (const char of segment) {
+    const step = vlqStep(accumulator, char);
+    accumulator = step.next;
+    if (step.decoded !== undefined) {
+      values.push(step.decoded);
+    }
+  }
+  requireTerminatedVlq(accumulator);
+  return values;
+}
+
+/**
+ * @param {string} rawSegment
+ * @returns {number[]}
+ */
+function decodeSegmentValues(rawSegment) {
+  const values = decodeVlqValues(rawSegment);
+  if (!SEGMENT_FIELD_COUNTS.has(values.length)) {
+    throw new Error("source map segment must contain 1, 4, or 5 VLQ fields");
+  }
+  return values;
+}
+
+/**
+ * @param {DecoderState} state
+ * @param {readonly number[]} values
+ * @returns {DecoderState}
+ */
+function advance(state, values) {
+  const [column = NO_DELTA, source = NO_DELTA, line = NO_DELTA, originalColumn = NO_DELTA, name] = values;
+  const generatedColumn = state.generatedColumn + column;
+  if (values.length === GENERATED_COLUMN_ONLY) {
+    return { ...state, generatedColumn };
+  }
+  return {
+    generatedColumn,
+    name: name === undefined ? state.name : state.name + name,
+    originalColumn: state.originalColumn + originalColumn,
+    originalLine: state.originalLine + line,
+    source: state.source + source
+  };
+}
+
+/**
+ * @param {DecoderState} state
+ * @param {number} fieldCount
+ * @returns {MappingSegment}
+ */
+function segmentFromState({ generatedColumn, name, originalColumn, originalLine, source }, fieldCount) {
+  if (fieldCount === GENERATED_COLUMN_ONLY) {
+    return { generatedColumn };
+  }
+  const located = { generatedColumn, originalColumn, originalLine, source };
+  return fieldCount === SEGMENT_WITH_NAME ? { ...located, name } : located;
+}
+
+/**
+ * @param {string} rawLine
+ * @param {DecoderState} initialState
+ * @returns {{ readonly segments: readonly MappingSegment[], readonly state: DecoderState }}
+ */
+function decodeLine(rawLine, initialState) {
+  /** @type {MappingSegment[]} */
+  const segments = [];
+  let state = { ...initialState, generatedColumn: NO_DELTA };
+  for (const rawSegment of rawLine.split(",")) {
+    if (rawSegment !== "") {
+      const values = decodeSegmentValues(rawSegment);
+      state = advance(state, values);
+      segments.push(segmentFromState(state, values.length));
+    }
+  }
+  return { segments, state };
+}
+
+/**
+ * @param {string} mappings
+ * @returns {readonly (readonly MappingSegment[])[]}
+ */
+function decodedMappingSegments(mappings) {
+  /** @type {(readonly MappingSegment[])[]} */
+  const lines = [];
+  let state = INITIAL_STATE;
+  for (const rawLine of mappings.split(";")) {
+    const decoded = decodeLine(rawLine, state);
+    lines.push(decoded.segments);
+    ({ state } = decoded);
+  }
+  return lines;
+}
+
+/**
+ * @param {unknown} source
+ * @returns {string}
+ */
+function safeOriginalSourceForReport(source) {
+  const value = typeof source === "string" ? fileReference(source.trim()) : "";
+  if (value === "") {
+    throw new Error("source map segment references an invalid source value");
+  }
+  if (value.startsWith("file://") || path.isAbsolute(value) || WINDOWS_DRIVE_RE.test(value)) {
+    throw new Error("source map source path must be stripped before symbolication proof");
+  }
+  return value;
+}
+
+/**
+ * @param {readonly MappingSegment[]} segments
+ * @param {number} generatedColumnIndex
+ * @returns {MappingSegment | undefined}
+ */
+function bestSegment(segments, generatedColumnIndex) {
+  const firstAfter = segments.findIndex((segment) => segment.generatedColumn > generatedColumnIndex);
+  return (firstAfter === NOT_FOUND ? segments : segments.slice(NO_DELTA, firstAfter)).at(LAST);
+}
+
+/**
+ * @param {unknown} names
+ * @param {number | undefined} nameIndex
+ * @returns {{ readonly name?: string }}
+ */
+function originalName(names, nameIndex) {
+  if (!Array.isArray(names) || nameIndex === undefined || nameIndex < NO_DELTA || nameIndex >= names.length) {
+    return {};
+  }
+  /** @type {readonly unknown[]} */
+  const list = names;
+  const name = list[nameIndex];
+  return typeof name === "string" && name !== "" ? { name } : {};
+}
+
+/**
+ * @param {ValidSourceMap} payload
+ * @param {number} generatedLine
+ * @param {number} generatedColumn
+ * @returns {OriginalPosition}
+ */
+function originalPositionFor(payload, generatedLine, generatedColumn) {
+  const lines = decodedMappingSegments(payload.mappings);
+  if (generatedLine - ONE_BASED_OFFSET >= lines.length) {
+    throw new Error("generated line is outside source map mappings");
+  }
+  const best = bestSegment(lines[generatedLine - ONE_BASED_OFFSET] ?? [], generatedColumn - ONE_BASED_OFFSET);
+  if (best?.source === undefined || best.originalLine === undefined || best.originalColumn === undefined) {
+    throw new Error("no original source mapping found for generated frame");
+  }
+  const { source: sourceIndex } = best;
+  if (!Number.isInteger(sourceIndex) || sourceIndex < NO_DELTA || sourceIndex >= payload.sources.length) {
+    throw new Error("source map segment references an invalid source index");
+  }
+  return {
+    column: best.originalColumn + ONE_BASED_OFFSET,
+    line: best.originalLine + ONE_BASED_OFFSET,
+    source: safeOriginalSourceForReport(payload.sources[sourceIndex]),
+    ...originalName(payload.names, best.name)
+  };
+}
+
+export { originalPositionFor };

package/release-artifacts-prepare.js

@@ -0,0 +1,297 @@
+import { RUNTIME_DEBUG_ID_MARKER, generateDebugId, sourceStartsWithDirective, sourceWithDebugId } from "./release-artifacts-debug-id.js";
+import { inspectArtifactFiles, iterMinifiedSourceFiles, readSourceMap } from "./release-artifacts-inspect.js";
+import { mapInOrder, pathExists, readText, realPath, sortJson, sourceMapDebugId, stableJson } from "./release-artifacts-common.js";
+import path from "node:path";
+import { writeFile } from "node:fs/promises";
+
+/**
+ * @import { JsonObject } from "./release-artifacts-common.js"
+ * @import { ArtifactInspection } from "./release-artifacts-inspect.js"
+ * @typedef {{ readonly sourcePrefixes: readonly string[], readonly stripSourcesContent: boolean }} PrivacyOptions
+ * @typedef {{ readonly errors: readonly string[], readonly status: "blocked" | "ready", readonly warnings: readonly string[] }} Validation
+ * @typedef {{
+ *   readonly changes: readonly string[],
+ *   readonly debugId?: string,
+ *   readonly path: string,
+ *   readonly sourceMapPath?: string,
+ *   readonly validation: Validation
+ * }} ArtifactPlan
+ * @typedef {{
+ *   readonly buildDir: string,
+ *   readonly stripSourcePrefixes: readonly string[],
+ *   readonly stripSourcesContent: boolean,
+ *   readonly write: boolean
+ * }} DebugIdPlanOptions
+ */
+
+const JSON_INDENT = 2;
+const SCRIPT_VERSION = "0.1.0";
+const NO_ITEMS = 0;
+const TRAILING_SLASHES_RE = /\/+$/u;
+
+/**
+ * @param {readonly string[]} values
+ * @returns {Promise<string[]>}
+ */
+async function normalizeSourcePrefixes(values) {
+  const candidates = await mapInOrder(values, async (value) => [
+    path.resolve(value),
+    (await pathExists(value)) ? await realPath(value) : path.resolve(value)
+  ]);
+  /** @type {string[]} */
+  const prefixes = [];
+  for (const candidate of candidates.flat()) {
+    const normalized = candidate.split(path.sep).join("/").replace(TRAILING_SLASHES_RE, "");
+    if (normalized !== "" && !prefixes.includes(normalized)) {
+      prefixes.push(normalized);
+    }
+  }
+  return prefixes;
+}
+
+/**
+ * @param {string} source
+ * @param {readonly string[]} prefixes
+ * @returns {string}
+ */
+function sourceWithoutPrefix(source, prefixes) {
+  const normalized = source.replaceAll("\\", "/");
+  for (const prefix of prefixes) {
+    const marker = `${prefix}/`;
+    if (normalized === prefix) {
+      return path.posix.basename(prefix);
+    }
+    if (normalized.startsWith(marker)) {
+      return normalized.slice(marker.length);
+    }
+  }
+  return source;
+}
+
+/**
+ * @param {JsonObject} payload
+ * @param {readonly string[]} prefixes
+ * @returns {unknown[] | undefined}
+ */
+function sourceMapSourcesWithoutPrefixes(payload, prefixes) {
+  const { sources } = payload;
+  if (prefixes.length === NO_ITEMS || !Array.isArray(sources)) {
+    return undefined;
+  }
+  /** @type {readonly unknown[]} */
+  const original = sources;
+  const updated = original.map((source) => (typeof source === "string" ? sourceWithoutPrefix(source, prefixes) : source));
+  return JSON.stringify(updated) === JSON.stringify(original) ? undefined : updated;
+}
+
+/**
+ * @param {JsonObject} payload
+ * @param {PrivacyOptions} options
+ * @returns {JsonObject}
+ */
+function sourceMapPayloadForDebugId(payload, { sourcePrefixes, stripSourcesContent }) {
+  const updatedSources = sourceMapSourcesWithoutPrefixes(payload, sourcePrefixes);
+  if (!stripSourcesContent && updatedSources === undefined) {
+    return payload;
+  }
+  const updated = updatedSources === undefined ? payload : { ...payload, sources: updatedSources };
+  if (!stripSourcesContent) {
+    return { ...updated };
+  }
+  const keys = Object.keys(updated).filter((key) => key !== "sourcesContent");
+  return Object.fromEntries(keys.map((key) => [key, updated[key]]));
+}
+
+/**
+ * @param {JsonObject} payload
+ * @param {string} debugId
+ * @param {PrivacyOptions & { readonly shiftGeneratedLines: boolean }} options
+ * @returns {JsonObject}
+ */
+function sourceMapWithPrivacyUpdates(payload, debugId, options) {
+  const privacyUpdated = sourceMapPayloadForDebugId(payload, options);
+  const { shiftGeneratedLines } = options;
+  if (sourceMapDebugId(payload) !== undefined && privacyUpdated === payload && !shiftGeneratedLines) {
+    return payload;
+  }
+  const { mappings } = privacyUpdated;
+  return {
+    ...privacyUpdated,
+    ...(sourceMapDebugId(privacyUpdated) === undefined ? { debug_id: debugId } : {}),
+    ...(shiftGeneratedLines && typeof mappings === "string" ? { mappings: `;${mappings}` } : {})
+  };
+}
+
+/**
+ * @param {ArtifactInspection} inspection
+ * @param {boolean} needsRuntimeDebugId
+ * @returns {string[]}
+ */
+function runtimeInjectionErrors({ jsSource, sourceMapPayload }, needsRuntimeDebugId) {
+  /** @type {string[]} */
+  const errors = [];
+  if (needsRuntimeDebugId && sourceStartsWithDirective(jsSource)) {
+    errors.push("runtime Debug ID injection cannot precede a script directive");
+  }
+  const mappings = sourceMapPayload?.["mappings"];
+  if (needsRuntimeDebugId && sourceMapPayload !== undefined && (typeof mappings !== "string" || mappings === "")) {
+    errors.push("source map mappings must be a non-empty string before runtime Debug ID injection");
+  }
+  return errors;
+}
+
+/**
+ * @param {ArtifactInspection} inspection
+ * @param {JsonObject} payload
+ * @param {PrivacyOptions} options
+ * @returns {{ readonly changes: readonly string[], readonly debugId: string }}
+ */
+function debugIdChanges({ jsDebugId, jsSource, mapDebugId, relJs }, payload, options) {
+  const existing = jsDebugId ?? mapDebugId;
+  if (existing === undefined) {
+    return {
+      changes: ["minifiedSource.debugId", "sourceMap.debug_id"],
+      debugId: generateDebugId(relJs, jsSource, sourceMapPayloadForDebugId(payload, options))
+    };
+  }
+  return {
+    changes: [
+      ...(jsDebugId === undefined ? ["minifiedSource.debugId"] : []),
+      ...(mapDebugId === undefined ? ["sourceMap.debug_id"] : [])
+    ],
+    debugId: existing
+  };
+}
+
+/**
+ * @param {ArtifactInspection} inspection
+ * @param {JsonObject} payload
+ * @param {PrivacyOptions & { readonly needsRuntimeDebugId: boolean }} options
+ * @returns {{ readonly changes: readonly string[], readonly debugId: string }}
+ */
+function plannedChanges(inspection, payload, options) {
+  const { changes, debugId } = debugIdChanges(inspection, payload, options);
+  return {
+    changes: [
+      ...(options.needsRuntimeDebugId ? ["minifiedSource.runtimeDebugId"] : []),
+      ...changes,
+      ...(options.stripSourcesContent && "sourcesContent" in payload ? ["sourceMap.sourcesContent"] : []),
+      ...(sourceMapSourcesWithoutPrefixes(payload, options.sourcePrefixes) === undefined ? [] : ["sourceMap.sources"])
+    ],
+    debugId
+  };
+}
+
+/**
+ * @param {string} jsPath
+ * @param {string} buildDir
+ * @param {PrivacyOptions} options
+ * @returns {Promise<ArtifactPlan>}
+ */
+async function buildArtifactPlan(jsPath, buildDir, options) {
+  const inspection = await inspectArtifactFiles(jsPath, buildDir);
+  const { relJs, sourceMapPayload, sourceMapRel } = inspection;
+  const needsRuntimeDebugId = !inspection.jsSource.includes(RUNTIME_DEBUG_ID_MARKER);
+  const errors = [...inspection.errors, ...runtimeInjectionErrors(inspection, needsRuntimeDebugId)];
+  const { changes, debugId } =
+    errors.length === NO_ITEMS && sourceMapPayload !== undefined
+      ? plannedChanges(inspection, sourceMapPayload, { ...options, needsRuntimeDebugId })
+      : { changes: [], debugId: inspection.jsDebugId ?? inspection.mapDebugId };
+  return {
+    changes,
+    ...(debugId === undefined ? {} : { debugId }),
+    path: relJs,
+    ...(sourceMapRel === undefined ? {} : { sourceMapPath: sourceMapRel }),
+    validation: { errors, status: errors.length > NO_ITEMS ? "blocked" : "ready", warnings: inspection.warnings }
+  };
+}
+
+/**
+ * @param {string} jsPath
+ * @param {string} debugId
+ * @param {string} relativePath
+ * @returns {Promise<string>}
+ */
+async function writeSourceDebugId(jsPath, debugId, relativePath) {
+  const jsSource = await readText(jsPath);
+  const updatedSource = sourceWithDebugId(jsSource, debugId, relativePath);
+  if (updatedSource !== jsSource) {
+    await writeFile(jsPath, updatedSource, "utf8");
+  }
+  return jsSource;
+}
+
+/**
+ * @param {string} mapPath
+ * @param {string} relativePath
+ * @returns {Promise<JsonObject>}
+ */
+async function readSourceMapForWrite(mapPath, relativePath) {
+  const { errors, payload } = await readSourceMap(mapPath);
+  if (payload === undefined || errors.length > NO_ITEMS) {
+    throw new Error(`${relativePath}: source map became unreadable before write`);
+  }
+  return payload;
+}
+
+/**
+ * @param {ArtifactPlan} artifact
+ * @param {string} buildDir
+ * @param {PrivacyOptions} options
+ * @returns {Promise<void>}
+ */
+async function applyArtifactPlan(artifact, buildDir, options) {
+  const { debugId, sourceMapPath } = artifact;
+  if (debugId === undefined || sourceMapPath === undefined) {
+    return;
+  }
+  const mapPath = path.join(buildDir, sourceMapPath);
+  const jsSource = await writeSourceDebugId(path.join(buildDir, artifact.path), debugId, artifact.path);
+  const payload = await readSourceMapForWrite(mapPath, artifact.path);
+  const shiftGeneratedLines = !jsSource.includes(RUNTIME_DEBUG_ID_MARKER);
+  const updatedPayload = sourceMapWithPrivacyUpdates(payload, debugId, { ...options, shiftGeneratedLines });
+  if (stableJson(updatedPayload) !== stableJson(payload)) {
+    await writeFile(mapPath, `${JSON.stringify(sortJson(updatedPayload), undefined, JSON_INDENT)}\n`, "utf8");
+  }
+}
+
+/**
+ * @param {readonly ArtifactPlan[]} artifacts
+ * @param {(artifact: ArtifactPlan) => readonly string[]} messages
+ * @returns {string[]}
+ */
+function prefixedMessages(artifacts, messages) {
+  return artifacts.flatMap((artifact) => messages(artifact).map((message) => `${artifact.path}: ${message}`));
+}
+
+/**
+ * @param {DebugIdPlanOptions} options
+ * @returns {Promise<Readonly<Record<string, unknown>> & { readonly validation: Validation }>}
+ */
+async function createDebugIdPlan({ buildDir, stripSourcePrefixes, stripSourcesContent, write }) {
+  const sourcePrefixes = await normalizeSourcePrefixes(stripSourcePrefixes);
+  const artifactOptions = { sourcePrefixes, stripSourcesContent };
+  const artifacts = await mapInOrder(await iterMinifiedSourceFiles(buildDir), async (filePath) =>
+    buildArtifactPlan(filePath, buildDir, artifactOptions));
+  const errors = [
+    ...(artifacts.length === NO_ITEMS ? ["no JavaScript release artifact files found in build directory"] : []),
+    ...prefixedMessages(artifacts, (artifact) => artifact.validation.errors)
+  ];
+  const warnings = prefixedMessages(artifacts, (artifact) => artifact.validation.warnings);
+  const status = errors.length > NO_ITEMS ? "blocked" : "ready";
+  const writeApplied = write && status === "ready";
+  if (writeApplied) {
+    await mapInOrder(artifacts, async (artifact) => applyArtifactPlan(artifact, buildDir, artifactOptions));
+  }
+  return {
+    artifacts,
+    manifestVersion: 1,
+    stripSourcePrefixCount: stripSourcePrefixes.length,
+    stripSourcesContent,
+    tool: { name: "logbrew-js-release-artifact-debug-id-prep", version: SCRIPT_VERSION },
+    validation: { errors, status, warnings },
+    writeApplied
+  };
+}
+
+export { createDebugIdPlan };