@logbrew/sdk 0.1.37 → 0.1.38

package/issue-evidence.cjs

@@ -0,0 +1,256 @@
+"use strict";
+
+const { SdkError } = require("./sdk-error.cjs");
+const { boundedIdentity, optionalText } = require("./issue-text.cjs");
+const { optionalEntry, rejectUnknownKeys, requireObject } = require("./validation.cjs");
+
+/**
+ * @import { IssueDiagnosticEvidence, IssueImpactEvidence, IssueLikelyFixArea } from "./index.cjs"
+ * @import { DeepReadonly } from "./validation.cjs"
+ * @typedef {"capturedFields" | "missingFields" | "redactedFields" | "truncatedFields"} EvidenceFieldKey
+ * @typedef {Pick<IssueDiagnosticEvidence, EvidenceFieldKey>} EvidenceFieldLists
+ */
+
+const MAX_DIAGNOSTIC_IDENTITY_LENGTH = 256;
+const MAX_DIAGNOSTIC_CAUSE_LENGTH = 1024;
+const MAX_DIAGNOSTIC_OUTCOME_LENGTH = 512;
+const MAX_DIAGNOSTIC_FIELDS = 32;
+const MIN_DIAGNOSTIC_FIELDS = 1;
+const MIN_COORDINATE = 1;
+const MAX_COORDINATE = 2_147_483_647;
+const NO_FIELDS = 0;
+const EVIDENCE_FIELD_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/u;
+const WINDOWS_DRIVE_PATTERN = /^[A-Za-z]:\//u;
+/** @type {readonly EvidenceFieldKey[]} */
+const EVIDENCE_FIELD_KEYS = ["capturedFields", "missingFields", "redactedFields", "truncatedFields"];
+const EVIDENCE_KEYS = new Set(["likelyRootCause", "likelyFixArea", "impact", ...EVIDENCE_FIELD_KEYS]);
+const FIX_AREA_KEYS = new Set(["component", "module", "function", "file", "line", "column", "inApp"]);
+const IMPACT_KEYS = new Set(["affectedUserSegment", "failedAction", "userVisibleOutcome"]);
+/** @type {readonly ["component", "module", "function"]} */
+const FIX_AREA_IDENTITY_KEYS = ["component", "module", "function"];
+/** @type {readonly ["affectedUserSegment", "failedAction"]} */
+const IMPACT_IDENTITY_KEYS = ["affectedUserSegment", "failedAction"];
+
+/**
+ * @template {string} Field
+ * @param {Readonly<Record<string, unknown>>} source
+ * @param {readonly Field[]} fields
+ * @param {string} label
+ * @returns {{ [Key in Field]?: string }}
+ */
+function identityFields(source, fields, label) {
+  /** @type {{ [Key in Field]?: string }} */
+  const validated = {};
+  for (const field of fields) {
+    const value = source[field];
+    if (value !== undefined) {
+      validated[field] = boundedIdentity(`${label} ${field}`, value, MAX_DIAGNOSTIC_IDENTITY_LENGTH);
+    }
+  }
+  return validated;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function safeRelativeSourcePath(value) {
+  const path = boundedIdentity("issue evidence likelyFixArea file", value, MAX_DIAGNOSTIC_IDENTITY_LENGTH).replaceAll("\\", "/");
+  if (
+    path.startsWith("/")
+    || WINDOWS_DRIVE_PATTERN.test(path)
+    || path.includes("://")
+    || path.split("/").some((part) => part === "" || part === "." || part === "..")
+  ) {
+    throw new SdkError("validation_error", "issue evidence likelyFixArea file must be a safe relative path");
+  }
+  return path;
+}
+
+/**
+ * @param {"line" | "column"} key
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+function optionalCoordinate(key, value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "number" || !Number.isInteger(value) || value < MIN_COORDINATE || value > MAX_COORDINATE) {
+    throw new SdkError("validation_error", `issue evidence likelyFixArea ${key} must be a positive integer`);
+  }
+  return value;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean | undefined}
+ */
+function optionalInApp(value) {
+  if (value !== undefined && typeof value !== "boolean") {
+    throw new SdkError("validation_error", "issue evidence likelyFixArea inApp must be a boolean");
+  }
+  return value;
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} source
+ * @returns {Omit<IssueLikelyFixArea, "inApp">}
+ */
+function fixAreaLocation(source) {
+  const identities = identityFields(source, FIX_AREA_IDENTITY_KEYS, "issue evidence likelyFixArea");
+  const file = source["file"] === undefined ? undefined : safeRelativeSourcePath(source["file"]);
+  const line = optionalCoordinate("line", source["line"]);
+  const column = optionalCoordinate("column", source["column"]);
+  return {
+    ...identities,
+    ...optionalEntry("file", file),
+    ...optionalEntry("line", line),
+    ...optionalEntry("column", column)
+  };
+}
+
+/**
+ * @param {unknown} area
+ * @returns {IssueLikelyFixArea | undefined}
+ */
+function validateLikelyFixArea(area) {
+  if (area === undefined) {
+    return undefined;
+  }
+  const source = requireObject("issue evidence likelyFixArea", area);
+  rejectUnknownKeys("issue evidence likelyFixArea", source, FIX_AREA_KEYS);
+  const location = fixAreaLocation(source);
+  const inApp = optionalInApp(source["inApp"]);
+  if (Object.keys(location).length === NO_FIELDS) {
+    throw new SdkError("validation_error", "issue evidence likelyFixArea must identify a code location");
+  }
+  return { ...location, ...optionalEntry("inApp", inApp) };
+}
+
+/**
+ * @param {unknown} impact
+ * @returns {IssueImpactEvidence | undefined}
+ */
+function validateImpactEvidence(impact) {
+  if (impact === undefined) {
+    return undefined;
+  }
+  const source = requireObject("issue evidence impact", impact);
+  rejectUnknownKeys("issue evidence impact", source, IMPACT_KEYS);
+  const validated = {
+    ...identityFields(source, IMPACT_IDENTITY_KEYS, "issue evidence impact"),
+    ...optionalEntry(
+      "userVisibleOutcome",
+      optionalText("issue evidence impact userVisibleOutcome", source["userVisibleOutcome"], MAX_DIAGNOSTIC_OUTCOME_LENGTH)
+    )
+  };
+  if (Object.keys(validated).length === NO_FIELDS) {
+    throw new SdkError("validation_error", "issue evidence impact must contain at least one field");
+  }
+  return validated;
+}
+
+/**
+ * @param {unknown} field
+ * @returns {field is string}
+ */
+function isEvidenceField(field) {
+  return typeof field === "string" && EVIDENCE_FIELD_PATTERN.test(field);
+}
+
+/**
+ * @param {EvidenceFieldKey} key
+ * @param {unknown} fields
+ * @returns {string[] | undefined}
+ */
+function validateEvidenceFields(key, fields) {
+  if (fields === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(fields) || fields.length < MIN_DIAGNOSTIC_FIELDS || fields.length > MAX_DIAGNOSTIC_FIELDS) {
+    throw new SdkError("validation_error", `issue evidence ${key} must contain 1-${MAX_DIAGNOSTIC_FIELDS} fields`);
+  }
+  /** @type {readonly unknown[]} */
+  const list = fields;
+  const identifiers = list.filter((field) => isEvidenceField(field));
+  if (new Set(list).size !== list.length || identifiers.length !== list.length) {
+    throw new SdkError("validation_error", `issue evidence ${key} fields must be unique bounded identifiers`);
+  }
+  return identifiers;
+}
+
+/**
+ * @param {DeepReadonly<EvidenceFieldLists>} lists
+ * @returns {void}
+ */
+function rejectConflictingFields(lists) {
+  const present = new Set();
+  for (const field of Object.values(lists).flat()) {
+    if (present.has(field)) {
+      throw new SdkError("validation_error", `issue evidence field ${field} has conflicting states`);
+    }
+    present.add(field);
+  }
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} source
+ * @returns {EvidenceFieldLists}
+ */
+function evidenceFieldLists(source) {
+  /** @type {EvidenceFieldLists} */
+  const lists = {};
+  for (const key of EVIDENCE_FIELD_KEYS) {
+    const fields = validateEvidenceFields(key, source[key]);
+    if (fields !== undefined) {
+      lists[key] = fields;
+    }
+  }
+  rejectConflictingFields(lists);
+  return lists;
+}
+
+/**
+ * @param {unknown} evidence
+ * @returns {IssueDiagnosticEvidence | undefined}
+ */
+function validateIssueEvidence(evidence) {
+  if (evidence === undefined) {
+    return undefined;
+  }
+  const source = requireObject("issue evidence", evidence);
+  rejectUnknownKeys("issue evidence", source, EVIDENCE_KEYS);
+  const validated = {
+    ...optionalEntry(
+      "likelyRootCause",
+      optionalText("issue evidence likelyRootCause", source["likelyRootCause"], MAX_DIAGNOSTIC_CAUSE_LENGTH)
+    ),
+    ...optionalEntry("likelyFixArea", validateLikelyFixArea(source["likelyFixArea"])),
+    ...optionalEntry("impact", validateImpactEvidence(source["impact"])),
+    ...evidenceFieldLists(source)
+  };
+  if (Object.keys(validated).length === NO_FIELDS) {
+    throw new SdkError("validation_error", "issue evidence must contain at least one field");
+  }
+  return validated;
+}
+
+/**
+ * @param {DeepReadonly<IssueDiagnosticEvidence>} evidence
+ * @returns {DeepReadonly<IssueDiagnosticEvidence>}
+ */
+function cloneIssueEvidence(evidence) {
+  const { capturedFields, impact, likelyFixArea, missingFields, redactedFields, truncatedFields } = evidence;
+  return {
+    ...evidence,
+    ...optionalEntry("likelyFixArea", likelyFixArea === undefined ? undefined : { ...likelyFixArea }),
+    ...optionalEntry("impact", impact === undefined ? undefined : { ...impact }),
+    ...optionalEntry("capturedFields", capturedFields === undefined ? undefined : [...capturedFields]),
+    ...optionalEntry("missingFields", missingFields === undefined ? undefined : [...missingFields]),
+    ...optionalEntry("redactedFields", redactedFields === undefined ? undefined : [...redactedFields]),
+    ...optionalEntry("truncatedFields", truncatedFields === undefined ? undefined : [...truncatedFields])
+  };
+}
+
+module.exports = { cloneIssueEvidence, validateIssueEvidence };

package/issue-exception.cjs

@@ -0,0 +1,263 @@
+"use strict";
+
+const { SdkError } = require("./sdk-error.cjs");
+const { validateIssueStackFrames } = require("./issue-stack-frames.cjs");
+const { boundedIdentity, optionalIdentity, optionalText, requireMachineName } = require("./issue-text.cjs");
+const { isAllowedValue, optionalEntry, rejectUnknownKeys, requireObject } = require("./validation.cjs");
+
+/**
+ * @import {
+ *   IssueException,
+ *   IssueExceptionChain,
+ *   IssueExceptionChainEntry,
+ *   IssueExceptionMechanism,
+ *   IssueExceptionMessageState,
+ *   IssueExceptionRelationship,
+ *   IssueExceptionStackFramesState
+ * } from "./index.cjs"
+ * @import { DeepReadonly } from "./validation.cjs"
+ * @typedef {Pick<IssueExceptionChainEntry, "id" | "parentId" | "relationship">} EntryLineage
+ * @typedef {Pick<IssueExceptionChainEntry, "message" | "messageState">} EntryMessage
+ * @typedef {Pick<IssueExceptionChainEntry, "stackFrames" | "stackFramesState">} EntryStack
+ */
+
+const MAX_ISSUE_EXCEPTIONS = 8;
+const MAX_EXCEPTION_TYPE_LENGTH = 256;
+const MAX_EXCEPTION_MESSAGE_LENGTH = 1024;
+const MAX_EXCEPTION_MODULE_LENGTH = 512;
+const ROOT_INDEX = 0;
+const NEXT_INDEX = 1;
+const EXCEPTION_KEYS = new Set(["type", "mechanism"]);
+const MECHANISM_KEYS = new Set(["type", "handled"]);
+const CHAIN_KEYS = new Set(["entries", "truncated"]);
+const ENTRY_KEYS = new Set([
+  "id",
+  "parentId",
+  "relationship",
+  "type",
+  "message",
+  "messageState",
+  "module",
+  "mechanism",
+  "stackFrames",
+  "stackFramesState"
+]);
+/** @type {ReadonlySet<IssueExceptionRelationship>} */
+const CHILD_RELATIONSHIPS = new Set(["cause", "context", "aggregate_member", "suppressed"]);
+/** @type {ReadonlySet<IssueExceptionMessageState>} */
+const MESSAGE_STATES = new Set(["captured", "truncated", "redacted", "not_captured"]);
+/** @type {ReadonlySet<IssueExceptionStackFramesState>} */
+const STACK_FRAMES_STATES = new Set(["captured", "truncated", "not_captured"]);
+
+/**
+ * @param {unknown} mechanism
+ * @returns {IssueExceptionMechanism | undefined}
+ */
+function validateIssueExceptionMechanism(mechanism) {
+  if (mechanism === undefined) {
+    return undefined;
+  }
+  const source = requireObject("issue exception mechanism", mechanism);
+  rejectUnknownKeys("issue exception mechanism", source, MECHANISM_KEYS);
+  const type = requireMachineName("issue exception mechanism type", source["type"]);
+  const { handled } = source;
+  if (typeof handled !== "boolean") {
+    throw new SdkError("validation_error", "issue exception mechanism handled must be a boolean");
+  }
+  return {
+    type,
+
+    handled
+  };
+}
+
+/**
+ * @param {unknown} exception
+ * @returns {IssueException | undefined}
+ */
+function validateIssueException(exception) {
+  if (exception === undefined) {
+    return undefined;
+  }
+  const source = requireObject("issue exception", exception);
+  rejectUnknownKeys("issue exception", source, EXCEPTION_KEYS);
+  const type = boundedIdentity("issue exception type", source["type"], MAX_EXCEPTION_TYPE_LENGTH);
+  const mechanism = validateIssueExceptionMechanism(source["mechanism"]);
+  return { type, ...optionalEntry("mechanism", mechanism) };
+}
+
+/**
+ * @param {string} type
+ * @param {string} mechanism
+ * @param {boolean} handled
+ * @returns {IssueException | undefined}
+ */
+function createIssueException(type, mechanism, handled) {
+  return validateIssueException({ mechanism: { handled, type: mechanism }, type });
+}
+
+/**
+ * @param {unknown} parentId
+ * @param {number} index
+ * @returns {parentId is number}
+ */
+function isParentIndex(parentId, index) {
+  return typeof parentId === "number" && Number.isInteger(parentId) && parentId >= ROOT_INDEX && parentId < index;
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} source
+ * @param {number} index
+ * @returns {EntryLineage}
+ */
+function entryLineage(source, index) {
+  const { id, parentId, relationship } = source;
+  if (typeof id !== "number" || !Number.isInteger(id) || id !== index) {
+    throw new SdkError("validation_error", `issue exceptionChain entry ${index} id must equal its array index`);
+  }
+  if (index === ROOT_INDEX) {
+    if (relationship !== "reported" || parentId !== undefined) {
+      throw new SdkError("validation_error", "issue exceptionChain entry 0 must be the parentless reported exception");
+    }
+    return { id, relationship };
+  }
+  if (typeof relationship !== "string" || !isAllowedValue(relationship, CHILD_RELATIONSHIPS) || !isParentIndex(parentId, index)) {
+    throw new SdkError("validation_error", `issue exceptionChain entry ${index} parent relationship is invalid`);
+  }
+  return { id, parentId, relationship };
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} source
+ * @param {number} index
+ * @returns {EntryMessage}
+ */
+function entryMessage(source, index) {
+  const { messageState } = source;
+  if (typeof messageState !== "string" || !isAllowedValue(messageState, MESSAGE_STATES)) {
+    throw new SdkError("validation_error", `issue exceptionChain entry ${index} messageState is invalid`);
+  }
+  const message = optionalText(`issue exceptionChain entry ${index} message`, source["message"], MAX_EXCEPTION_MESSAGE_LENGTH);
+  if ((messageState === "captured" || messageState === "truncated") !== (message !== undefined)) {
+    throw new SdkError("validation_error", `issue exceptionChain entry ${index} message does not match messageState`);
+  }
+  return { ...optionalEntry("message", message), messageState };
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} source
+ * @param {number} index
+ * @returns {EntryStack}
+ */
+function entryStack(source, index) {
+  const { stackFramesState } = source;
+  if (typeof stackFramesState !== "string" || !isAllowedValue(stackFramesState, STACK_FRAMES_STATES)) {
+    throw new SdkError("validation_error", `issue exceptionChain entry ${index} stackFramesState is invalid`);
+  }
+  const stackFrames = validateIssueStackFrames(source["stackFrames"]);
+  if ((stackFramesState === "captured" || stackFramesState === "truncated") !== (stackFrames !== undefined)) {
+    throw new SdkError("validation_error", `issue exceptionChain entry ${index} stackFrames do not match stackFramesState`);
+  }
+  return { ...optionalEntry("stackFrames", stackFrames), stackFramesState };
+}
+
+/**
+ * @param {unknown} entry
+ * @param {number} index
+ * @returns {IssueExceptionChainEntry}
+ */
+function validateIssueExceptionChainEntry(entry, index) {
+  const label = `issue exceptionChain entry ${index}`;
+  const source = requireObject(label, entry);
+  rejectUnknownKeys(label, source, ENTRY_KEYS);
+  const lineage = entryLineage(source, index);
+  const type = boundedIdentity(`${label} type`, source["type"], MAX_EXCEPTION_TYPE_LENGTH);
+  const message = entryMessage(source, index);
+  const moduleName = optionalIdentity(`${label} module`, source["module"], MAX_EXCEPTION_MODULE_LENGTH);
+  const mechanism = validateIssueExceptionMechanism(source["mechanism"]);
+  const stack = entryStack(source, index);
+  return {
+    ...lineage,
+    type,
+    ...message,
+    ...optionalEntry("module", moduleName),
+    ...optionalEntry("mechanism", mechanism),
+    ...stack
+  };
+}
+
+/**
+ * @param {readonly unknown[]} entries
+ * @returns {entries is readonly [unknown, ...unknown[]]}
+ */
+function hasChainEntries(entries) {
+  return entries.length >= NEXT_INDEX && entries.length <= MAX_ISSUE_EXCEPTIONS;
+}
+
+/**
+ * @param {unknown} entries
+ * @returns {readonly [unknown, ...unknown[]]}
+ */
+function requireChainEntries(entries) {
+  if (Array.isArray(entries)) {
+    /** @type {readonly unknown[]} */
+    const list = entries;
+    if (hasChainEntries(list)) {
+      return list;
+    }
+  }
+  throw new SdkError("validation_error", `issue exceptionChain entries must contain 1-${MAX_ISSUE_EXCEPTIONS} exceptions`);
+}
+
+/**
+ * @param {unknown} truncated
+ * @returns {boolean}
+ */
+function requireChainTruncated(truncated) {
+  if (typeof truncated !== "boolean") {
+    throw new SdkError("validation_error", "issue exceptionChain truncated must be a boolean");
+  }
+  return truncated;
+}
+
+/**
+ * @param {DeepReadonly<IssueExceptionChainEntry>} reported
+ * @param {DeepReadonly<IssueException> | undefined} legacyException
+ * @param {unknown} legacyStackFrames
+ * @returns {void}
+ */
+function requireReportedMatch(reported, legacyException, legacyStackFrames) {
+  const reportedException = { type: reported.type, ...optionalEntry("mechanism", reported.mechanism) };
+  if (legacyException === undefined || JSON.stringify(reportedException) !== JSON.stringify(legacyException)) {
+    throw new SdkError("validation_error", "issue exceptionChain reported exception must match exception");
+  }
+  const canonicalLegacyFrames = validateIssueStackFrames(legacyStackFrames);
+  const framesMatch = reported.stackFramesState === "not_captured"
+    ? canonicalLegacyFrames === undefined
+    : JSON.stringify(reported.stackFrames) === JSON.stringify(canonicalLegacyFrames);
+  if (!framesMatch) {
+    throw new SdkError("validation_error", "issue exceptionChain reported stack must match stackFrames");
+  }
+}
+
+/**
+ * @param {unknown} chain
+ * @param {DeepReadonly<IssueException> | undefined} legacyException
+ * @param {unknown} legacyStackFrames
+ * @returns {IssueExceptionChain | undefined}
+ */
+function validateIssueExceptionChain(chain, legacyException, legacyStackFrames) {
+  if (chain === undefined) {
+    return undefined;
+  }
+  const source = requireObject("issue exceptionChain", chain);
+  rejectUnknownKeys("issue exceptionChain", source, CHAIN_KEYS);
+  const [first, ...rest] = requireChainEntries(source["entries"]);
+  const truncated = requireChainTruncated(source["truncated"]);
+  const reported = validateIssueExceptionChainEntry(first, ROOT_INDEX);
+  const entries = [reported, ...rest.map((entry, offset) => validateIssueExceptionChainEntry(entry, offset + NEXT_INDEX))];
+  requireReportedMatch(reported, legacyException, legacyStackFrames);
+  return { entries, truncated };
+}
+
+module.exports = { createIssueException, validateIssueException, validateIssueExceptionChain };