@logbrew/sdk 0.1.38 → 0.1.39

package/release-artifacts-inspect.js

@@ -0,0 +1,213 @@
+import {
+  byteSize,
+  errorMessage,
+  fileReference,
+  isJsonObject,
+  mapInOrder,
+  pathExists,
+  readText,
+  relativeTo,
+  safeResolve,
+  sourceMapDebugId
+} from "./release-artifacts-common.js";
+import { findDebugId, findSourceMappingUrl } from "./release-artifacts-debug-id.js";
+import path from "node:path";
+import { readdir } from "node:fs/promises";
+
+/**
+ * @import { JsonObject } from "./release-artifacts-common.js"
+ * @typedef {{ readonly entryPath: string, readonly isDirectory: boolean, readonly isFile: boolean }} WalkEntry
+ * @typedef {{ readonly errors: readonly string[], readonly payload?: JsonObject }} SourceMapRead
+ * @typedef {{ readonly errors: readonly string[], readonly path?: string, readonly warnings: readonly string[] }} SourceMapLocation
+ * @typedef {{
+ *   readonly errors: readonly string[],
+ *   readonly mapDebugId?: string,
+ *   readonly payload?: JsonObject,
+ *   readonly relativePath?: string,
+ *   readonly size?: number
+ * }} SourceMapInspection
+ * @typedef {{
+ *   readonly errors: readonly string[],
+ *   readonly jsDebugId: string | undefined,
+ *   readonly jsSize: number,
+ *   readonly jsSource: string,
+ *   readonly mapDebugId: string | undefined,
+ *   readonly relJs: string,
+ *   readonly sourceMapPath: string | undefined,
+ *   readonly sourceMapPayload: JsonObject | undefined,
+ *   readonly sourceMapRel: string | undefined,
+ *   readonly sourceMapSize: number | undefined,
+ *   readonly sourceMappingUrl: string | undefined,
+ *   readonly warnings: readonly string[]
+ * }} ArtifactInspection
+ */
+
+const MINIFIED_SOURCE_SUFFIXES = [".js", ".mjs", ".bundle", ".jsbundle"];
+const URL_WITH_SCHEME_RE = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//u;
+const EMPTY_FILE_SIZE = 0;
+const ROOT_PREFIX_LENGTH = 1;
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<SourceMapRead>}
+ */
+async function readSourceMap(filePath) {
+  try {
+    /** @type {unknown} */
+    const payload = JSON.parse(await readText(filePath));
+    return isJsonObject(payload) ? { errors: [], payload } : { errors: ["source map must be a JSON object"] };
+  } catch (error) {
+    return { errors: [`source map is not valid JSON: ${errorMessage(error)}`] };
+  }
+}
+
+/**
+ * @param {string} jsPath
+ * @param {string} buildDir
+ * @param {string} reference
+ * @returns {Promise<SourceMapLocation>}
+ */
+async function resolveReferencedSourceMap(jsPath, buildDir, reference) {
+  const candidate = reference.startsWith("/")
+    ? path.join(buildDir, reference.slice(ROOT_PREFIX_LENGTH))
+    : path.join(path.dirname(jsPath), reference);
+  const resolved = await safeResolve(candidate, buildDir);
+  if (resolved === undefined) {
+    return { errors: ["sourceMappingURL resolves outside the build directory"], warnings: [] };
+  }
+  return { errors: [], path: resolved, warnings: [] };
+}
+
+/**
+ * @param {string} jsPath
+ * @param {string} buildDir
+ * @param {string | undefined} sourceMappingUrl
+ * @returns {Promise<SourceMapLocation>}
+ */
+async function resolveSourceMapPath(jsPath, buildDir, sourceMappingUrl) {
+  if (sourceMappingUrl === undefined) {
+    const fallback = `${jsPath}.map`;
+    const warnings = ["sourceMappingURL comment missing; checked sibling .map fallback"];
+    return (await pathExists(fallback)) ? { errors: [], path: fallback, warnings } : { errors: [], warnings };
+  }
+  const reference = fileReference(sourceMappingUrl);
+  if (reference.startsWith("data:")) {
+    return { errors: ["inline source maps are not accepted for release artifact manifests"], warnings: [] };
+  }
+  if (URL_WITH_SCHEME_RE.test(reference)) {
+    return { errors: ["external sourceMappingURL cannot be validated from the local build directory"], warnings: [] };
+  }
+  return resolveReferencedSourceMap(jsPath, buildDir, reference);
+}
+
+/**
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function isMinifiedSource(filePath) {
+  return !filePath.endsWith(".map") && MINIFIED_SOURCE_SUFFIXES.some((suffix) => filePath.endsWith(suffix));
+}
+
+/**
+ * @param {string} root
+ * @returns {Promise<string[]>}
+ */
+async function walkFiles(root) {
+  const entries = await readdir(root, { withFileTypes: true });
+  /** @type {WalkEntry[]} */
+  const descriptors = [];
+  for (const entry of entries) {
+    descriptors.push({ entryPath: path.join(root, entry.name), isDirectory: entry.isDirectory(), isFile: entry.isFile() });
+  }
+  const nested = await mapInOrder(descriptors, async ({ entryPath, isDirectory, isFile }) => {
+    if (isDirectory) {
+      return walkFiles(entryPath);
+    }
+    return isFile ? [entryPath] : [];
+  });
+  const results = nested.flat();
+  results.sort();
+  return results;
+}
+
+/**
+ * @param {string} buildDir
+ * @returns {Promise<string[]>}
+ */
+async function iterMinifiedSourceFiles(buildDir) {
+  const files = await walkFiles(buildDir);
+  return files.filter((filePath) => isMinifiedSource(filePath));
+}
+
+/**
+ * @param {string} sourceMapPath
+ * @param {string} relativePath
+ * @param {number} size
+ * @returns {Promise<SourceMapInspection>}
+ */
+async function inspectSourceMapPayload(sourceMapPath, relativePath, size) {
+  const { errors, payload } = await readSourceMap(sourceMapPath);
+  if (payload === undefined) {
+    return { errors, relativePath, size };
+  }
+  const mapDebugId = sourceMapDebugId(payload);
+  return mapDebugId === undefined
+    ? { errors, payload, relativePath, size }
+    : { errors, mapDebugId, payload, relativePath, size };
+}
+
+/**
+ * @param {string | undefined} sourceMapPath
+ * @param {string} buildDir
+ * @returns {Promise<SourceMapInspection>}
+ */
+async function inspectSourceMap(sourceMapPath, buildDir) {
+  if (sourceMapPath === undefined) {
+    return { errors: ["source map file is missing"] };
+  }
+  if (!(await pathExists(sourceMapPath))) {
+    return { errors: [`source map file is missing: ${relativeTo(buildDir, sourceMapPath)}`] };
+  }
+  const size = await byteSize(sourceMapPath);
+  if (size === EMPTY_FILE_SIZE) {
+    return { errors: [`source map file is empty: ${relativeTo(buildDir, sourceMapPath)}`] };
+  }
+  return inspectSourceMapPayload(sourceMapPath, relativeTo(buildDir, sourceMapPath), size);
+}
+
+/**
+ * @param {string} jsPath
+ * @param {string} buildDir
+ * @returns {Promise<ArtifactInspection>}
+ */
+async function inspectArtifactFiles(jsPath, buildDir) {
+  const jsSize = await byteSize(jsPath);
+  const jsSource = await readText(jsPath);
+  const jsDebugId = findDebugId(jsSource);
+  const sourceMappingUrl = findSourceMappingUrl(jsSource);
+  const location = await resolveSourceMapPath(jsPath, buildDir, sourceMappingUrl);
+  const sourceMap = await inspectSourceMap(location.path, buildDir);
+  const { mapDebugId } = sourceMap;
+  const mismatch = jsDebugId !== undefined && mapDebugId !== undefined && jsDebugId !== mapDebugId;
+  return {
+    errors: [
+      ...(jsSize === EMPTY_FILE_SIZE ? ["minified source file is empty"] : []),
+      ...location.errors,
+      ...sourceMap.errors,
+      ...(mismatch ? ["minified source debugId does not match source map debugId"] : [])
+    ],
+    jsDebugId,
+    jsSize,
+    jsSource,
+    mapDebugId,
+    relJs: relativeTo(buildDir, jsPath),
+    sourceMapPath: location.path,
+    sourceMapPayload: sourceMap.payload,
+    sourceMapRel: sourceMap.relativePath,
+    sourceMapSize: sourceMap.size,
+    sourceMappingUrl,
+    warnings: location.warnings
+  };
+}
+
+export { inspectArtifactFiles, iterMinifiedSourceFiles, readSourceMap };

package/release-artifacts-issue-event.js

@@ -0,0 +1,99 @@
+import { isJsonObject } from "./release-artifacts-common.js";
+
+/**
+ * @import { JsonObject } from "./release-artifacts-common.js"
+ * @typedef {{ readonly issueId?: string, readonly metadataSource: string, readonly type: string }} IssueEventInput
+ */
+
+const FIRST_LINE = 1;
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function trimmedString(value) {
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+
+/**
+ * @param {JsonObject} issueEvent
+ * @returns {{ readonly input: IssueEventInput, readonly metadata: JsonObject }}
+ */
+function metadataFromIssueEvent(issueEvent) {
+  const { attributes, metadata } = issueEvent;
+  const attributesMetadata = isJsonObject(attributes) ? attributes["metadata"] : undefined;
+  if (isJsonObject(attributesMetadata)) {
+    const issueId = trimmedString(issueEvent["id"]);
+    return {
+      input: {
+        ...(issueId === undefined ? {} : { issueId }),
+        metadataSource: "attributes.metadata",
+        type: "sdk_issue_event"
+      },
+      metadata: attributesMetadata
+    };
+  }
+  if (isJsonObject(metadata)) {
+    return { input: { metadataSource: "metadata", type: "issue_attributes" }, metadata };
+  }
+  throw new Error("issue event must contain attributes.metadata or metadata");
+}
+
+/**
+ * @param {JsonObject} metadata
+ * @param {string} name
+ * @returns {string}
+ */
+function requireMetadataString(metadata, name) {
+  const value = trimmedString(metadata[name]);
+  if (value === undefined) {
+    throw new Error(`issue event metadata is missing ${name}`);
+  }
+  return value;
+}
+
+/**
+ * @param {JsonObject} metadata
+ * @param {string} name
+ * @returns {number}
+ */
+function requireMetadataPositiveInteger(metadata, name) {
+  const value = metadata[name];
+  if (typeof value !== "number" || !Number.isInteger(value) || value < FIRST_LINE) {
+    throw new Error(`issue event metadata ${name} must be a one-based positive integer`);
+  }
+  return value;
+}
+
+/**
+ * @param {JsonObject} metadata
+ * @param {JsonObject} manifest
+ * @returns {void}
+ */
+function requireMetadataMatchesManifest(metadata, manifest) {
+  for (const name of ["release", "environment", "service"]) {
+    if (manifest[name] !== requireMetadataString(metadata, name)) {
+      throw new Error(`issue event metadata ${name} does not match the manifest`);
+    }
+  }
+}
+
+/**
+ * @param {JsonObject} metadata
+ * @returns {string}
+ */
+function stackFrameFromIssueMetadata(metadata) {
+  const releaseArtifactType = requireMetadataString(metadata, "releaseArtifactType");
+  if (releaseArtifactType !== "sourcemap") {
+    throw new Error("issue event releaseArtifactType must be sourcemap");
+  }
+  const codeFile = trimmedString(metadata["releaseArtifactCodeFile"]) ?? trimmedString(metadata["errorFrameFile"]);
+  if (codeFile === undefined) {
+    throw new Error("issue event metadata is missing releaseArtifactCodeFile");
+  }
+  const line = requireMetadataPositiveInteger(metadata, "errorFrameLine");
+  const column = requireMetadataPositiveInteger(metadata, "errorFrameColumn");
+  return `${codeFile}:${String(line)}:${String(column)}`;
+}
+
+export { metadataFromIssueEvent, requireMetadataMatchesManifest, requireMetadataString, stackFrameFromIssueMetadata };

package/release-artifacts-manifest-artifact.js

@@ -0,0 +1,107 @@
+import { inspectArtifactFiles } from "./release-artifacts-inspect.js";
+import { joinUrlOrPath } from "./release-artifacts-urls.js";
+import { sha256File } from "./release-artifacts-common.js";
+
+/**
+ * @import { JsonObject } from "./release-artifacts-common.js"
+ * @import { ArtifactInspection } from "./release-artifacts-inspect.js"
+ * @typedef {{ readonly errors: readonly string[], readonly status: "blocked" | "ready", readonly warnings: readonly string[] }} Validation
+ * @typedef {{
+ *   readonly allowSourcesContent: boolean,
+ *   readonly buildDir: string,
+ *   readonly minifiedPathPrefix: string
+ * }} ManifestArtifactOptions
+ * @typedef {{
+ *   readonly minifiedSource: JsonObject & { readonly path: string },
+ *   readonly validation: Validation
+ * }} ManifestArtifact
+ */
+
+const NO_ITEMS = 0;
+
+/**
+ * @param {JsonObject} payload
+ * @param {boolean} allowSourcesContent
+ * @returns {{ readonly errors: readonly string[], readonly warnings: readonly string[] }}
+ */
+function validateSourceMapPayload(payload, allowSourcesContent) {
+  const { mappings, sources, version } = payload;
+  const hasSourcesContent = "sourcesContent" in payload;
+  return {
+    errors: [
+      ...(version === undefined ? ["source map version is required"] : []),
+      ...(!Array.isArray(sources) || sources.length === NO_ITEMS ? ["source map sources must be a non-empty array"] : []),
+      ...(typeof mappings !== "string" || mappings === "" ? ["source map mappings must be a non-empty string"] : []),
+      ...(hasSourcesContent && !allowSourcesContent
+        ? ["source map contains sourcesContent; rerun with --allow-sources-content only if policy permits it"]
+        : [])
+    ],
+    warnings:
+      hasSourcesContent && allowSourcesContent
+        ? ["source map contains sourcesContent; ensure app policy permits source upload"]
+        : []
+  };
+}
+
+/**
+ * @param {ArtifactInspection} inspection
+ * @param {boolean} allowSourcesContent
+ * @returns {Promise<{ readonly entry: JsonObject | undefined, readonly errors: readonly string[], readonly warnings: readonly string[] }>}
+ */
+async function sourceMapEntry(inspection, allowSourcesContent) {
+  const { mapDebugId, sourceMapPath, sourceMapPayload, sourceMapRel, sourceMapSize } = inspection;
+  if (sourceMapPayload === undefined || sourceMapPath === undefined || sourceMapRel === undefined) {
+    return { entry: undefined, errors: [], warnings: [] };
+  }
+  const { errors, warnings } = validateSourceMapPayload(sourceMapPayload, allowSourcesContent);
+  const { sources } = sourceMapPayload;
+  return {
+    entry: {
+      artifactSha256: await sha256File(sourceMapPath),
+      byteSize: sourceMapSize,
+      ...(mapDebugId === undefined ? {} : { debugId: mapDebugId }),
+      hasSourcesContent: "sourcesContent" in sourceMapPayload,
+      path: sourceMapRel,
+      sourceCount: Array.isArray(sources) ? sources.length : NO_ITEMS
+    },
+    errors,
+    warnings
+  };
+}
+
+/**
+ * @param {string} jsPath
+ * @param {ManifestArtifactOptions} options
+ * @returns {Promise<ManifestArtifact & JsonObject>}
+ */
+async function buildManifestArtifact(jsPath, { allowSourcesContent, buildDir, minifiedPathPrefix }) {
+  const inspection = await inspectArtifactFiles(jsPath, buildDir);
+  const { jsDebugId, jsSize, mapDebugId, relJs, sourceMappingUrl } = inspection;
+  const sourceMap = await sourceMapEntry(inspection, allowSourcesContent);
+  const errors = [...inspection.errors, ...sourceMap.errors];
+  const missingDebugId = jsDebugId === undefined && mapDebugId === undefined;
+  const warnings = [
+    ...inspection.warnings,
+    ...sourceMap.warnings,
+    ...(missingDebugId ? ["no debugId found; backend matching must rely on release/environment/service and minified path"] : [])
+  ];
+  const debugId = jsDebugId ?? mapDebugId;
+  const minifiedUrl = joinUrlOrPath(minifiedPathPrefix, relJs);
+  const artifactSha256 = await sha256File(jsPath);
+  return {
+    artifactType: "javascript_source_map",
+    ...(debugId === undefined ? {} : { debugId }),
+    minifiedSource: {
+      artifactSha256,
+      byteSize: jsSize,
+      ...(jsDebugId === undefined ? {} : { debugId: jsDebugId }),
+      minifiedUrl,
+      path: relJs,
+      ...(sourceMappingUrl === undefined ? {} : { sourceMappingUrl })
+    },
+    sourceMap: sourceMap.entry ?? null,
+    validation: { errors, status: errors.length > NO_ITEMS ? "blocked" : "ready", warnings }
+  };
+}
+
+export { buildManifestArtifact };

package/release-artifacts-manifest.js

@@ -0,0 +1,77 @@
+import { buildManifestArtifact } from "./release-artifacts-manifest-artifact.js";
+import { iterMinifiedSourceFiles } from "./release-artifacts-inspect.js";
+import { mapInOrder } from "./release-artifacts-common.js";
+import { normalizeUrlOrPath } from "./release-artifacts-urls.js";
+
+/**
+ * @import { JsonObject } from "./release-artifacts-common.js"
+ * @import { ManifestArtifact, Validation } from "./release-artifacts-manifest-artifact.js"
+ * @typedef {{
+ *   readonly allowSourcesContent: boolean,
+ *   readonly buildDir: string,
+ *   readonly commitSha: string | undefined,
+ *   readonly environment: string,
+ *   readonly minifiedPathPrefix: string,
+ *   readonly projectId: string | undefined,
+ *   readonly release: string,
+ *   readonly repositoryUrl: string | undefined,
+ *   readonly service: string
+ * }} ManifestOptions
+ */
+
+const MANIFEST_VERSION = 1;
+const NO_ITEMS = 0;
+const SCRIPT_VERSION = "0.1.0";
+
+/**
+ * @param {readonly ManifestArtifact[]} artifacts
+ * @param {(artifact: ManifestArtifact) => readonly string[]} messages
+ * @returns {string[]}
+ */
+function prefixedMessages(artifacts, messages) {
+  return artifacts.flatMap((artifact) => messages(artifact).map((message) => `${artifact.minifiedSource.path}: ${message}`));
+}
+
+/**
+ * @param {string | undefined} repositoryUrl
+ * @param {string | undefined} commitSha
+ * @returns {JsonObject}
+ */
+function gitMetadata(repositoryUrl, commitSha) {
+  return {
+    ...(commitSha === undefined || commitSha === "" ? {} : { commitSha: commitSha.trim() }),
+    ...(repositoryUrl === undefined || repositoryUrl === "" ? {} : { repositoryUrl: repositoryUrl.trim() })
+  };
+}
+
+/**
+ * @param {ManifestOptions} options
+ * @returns {Promise<JsonObject & { readonly validation: Validation }>}
+ */
+async function createManifest(options) {
+  const { allowSourcesContent, buildDir, environment, projectId, release, service } = options;
+  const minifiedPathPrefix = normalizeUrlOrPath(options.minifiedPathPrefix.trim());
+  const artifacts = await mapInOrder(await iterMinifiedSourceFiles(buildDir), async (filePath) =>
+    buildManifestArtifact(filePath, { allowSourcesContent, buildDir, minifiedPathPrefix }));
+  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 git = gitMetadata(options.repositoryUrl, options.commitSha);
+  return {
+    artifactType: "javascript_source_map_manifest",
+    artifacts,
+    environment,
+    ...(Object.keys(git).length > NO_ITEMS ? { git } : {}),
+    manifestVersion: MANIFEST_VERSION,
+    minifiedPathPrefix,
+    ...(projectId === undefined ? {} : { projectId }),
+    release,
+    service,
+    uploader: { name: "logbrew-js-release-artifact-manifest", version: SCRIPT_VERSION },
+    validation: { errors, status: errors.length > NO_ITEMS ? "blocked" : "ready", warnings }
+  };
+}
+
+export { createManifest };