@veryfront/ext-content-mdx 0.1.1186 → 0.1.1189

package/esm/src/errors/veryfront-error.js

@@ -1,3 +1,20 @@
+import { isVeryfrontErrorInstance, snapshotKnownVeryfrontError, VeryfrontError, } from "./types.js";
+const apply = Reflect.apply;
+const arrayIsArray = Array.isArray;
+const createObject = Object.create;
+const defineProperty = Object.defineProperty;
+const getOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
+const getOwnPropertyDescriptors = Object.getOwnPropertyDescriptors;
+const getPrototypeOf = Object.getPrototypeOf;
+const hasOwn = Object.hasOwn;
+const objectEntries = Object.entries;
+const objectPrototype = Object.prototype;
+const numberIsFinite = Number.isFinite;
+const NativeArray = Array;
+const NativeError = Error;
+const NativeSet = Set;
+const NativeString = String;
+const captureStackTrace = Error.captureStackTrace;
 export function createError(error) {
     return error;
 }
@@ -11,51 +28,644 @@ export const isRenderError = isErrorType("render");
 export const isConfigError = isErrorType("config");
 export const isFileError = isErrorType("file");
 export const isNetworkError = isErrorType("network");
-/**
- * Convert a VeryfrontErrorData (plain object) to a throwable Error instance.
- *
- * Uses Error.captureStackTrace when available (V8 engines) to exclude toError()
- * from the stack trace, making the stack point to the actual call site.
- *
- * @see plans/architecture-audit/010.3-dual-veryfront-error-definitions.md
- */
-export function toError(veryfrontError) {
-    const error = new Error(veryfrontError.message);
+const SNAPSHOT_FAILED = Symbol("snapshot-failed");
+const INVALID_ERROR_DATA = Symbol("invalid-error-data");
+const MAX_SNAPSHOT_DEPTH = 16;
+const MAX_SNAPSHOT_ENTRIES = 10_000;
+const standardIsError = getOwnPropertyDescriptor(NativeError, "isError")?.value;
+function hasNativeErrorBrand(error) {
+    if (typeof standardIsError === "function") {
+        try {
+            return apply(standardIsError, NativeError, [error]);
+        }
+        catch {
+            return false;
+        }
+    }
+    // Compatibility path for engines predating Error.isError. Modern runtimes
+    // use the hook-free brand check above.
+    try {
+        return error instanceof NativeError;
+    }
+    catch {
+        return false;
+    }
+}
+function snapshotPlainValue(value, depth, state) {
+    if (value === null ||
+        value === undefined ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean" ||
+        typeof value === "bigint") {
+        return value;
+    }
+    if (typeof value !== "object" ||
+        depth >= MAX_SNAPSHOT_DEPTH ||
+        state.seen.has(value) ||
+        state.isProxy(value)) {
+        return SNAPSHOT_FAILED;
+    }
+    state.seen.add(value);
+    try {
+        if (arrayIsArray(value)) {
+            const descriptors = getOwnPropertyDescriptors(value);
+            const lengthDescriptor = descriptors["length"];
+            if (!lengthDescriptor ||
+                !("value" in lengthDescriptor) ||
+                typeof lengthDescriptor.value !== "number" ||
+                lengthDescriptor.value > state.remainingEntries) {
+                return SNAPSHOT_FAILED;
+            }
+            state.remainingEntries -= lengthDescriptor.value;
+            const result = new NativeArray(lengthDescriptor.value);
+            for (let index = 0; index < lengthDescriptor.value; index++) {
+                const descriptor = descriptors[String(index)];
+                if (!descriptor)
+                    continue;
+                if (!("value" in descriptor))
+                    return SNAPSHOT_FAILED;
+                const child = snapshotPlainValue(descriptor.value, depth + 1, state);
+                if (child === SNAPSHOT_FAILED)
+                    return SNAPSHOT_FAILED;
+                result[index] = child;
+            }
+            return result;
+        }
+        const prototype = getPrototypeOf(value);
+        if (prototype !== objectPrototype && prototype !== null)
+            return SNAPSHOT_FAILED;
+        const descriptors = getOwnPropertyDescriptors(value);
+        const entries = objectEntries(descriptors).filter(([, descriptor]) => descriptor.enumerable);
+        if (entries.length > state.remainingEntries)
+            return SNAPSHOT_FAILED;
+        state.remainingEntries -= entries.length;
+        const result = {};
+        for (const [key, descriptor] of entries) {
+            if (!("value" in descriptor))
+                return SNAPSHOT_FAILED;
+            const child = snapshotPlainValue(descriptor.value, depth + 1, state);
+            if (child === SNAPSHOT_FAILED)
+                return SNAPSHOT_FAILED;
+            defineProperty(result, key, {
+                configurable: true,
+                enumerable: true,
+                value: child,
+                writable: true,
+            });
+        }
+        return result;
+    }
+    catch {
+        return SNAPSHOT_FAILED;
+    }
+    finally {
+        state.seen.delete(value);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !arrayIsArray(value);
+}
+function isString(value) {
+    return typeof value === "string";
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && numberIsFinite(value);
+}
+function optionalField(source, key, predicate) {
+    if (!hasOwn(source, key) || source[key] === undefined)
+        return undefined;
+    return predicate(source[key]) ? source[key] : INVALID_ERROR_DATA;
+}
+function optionalContext(source, normalize) {
+    if (!hasOwn(source, "context") || source.context === undefined) {
+        return undefined;
+    }
+    return normalize(source.context);
+}
+function normalizeStringArray(value) {
+    if (!arrayIsArray(value))
+        return INVALID_ERROR_DATA;
+    const normalized = [];
+    for (const entry of value) {
+        if (!isString(entry))
+            return INVALID_ERROR_DATA;
+        normalized.push(entry);
+    }
+    return normalized;
+}
+function normalizeMissingDependencies(value) {
+    if (!arrayIsArray(value))
+        return INVALID_ERROR_DATA;
+    const normalized = [];
+    for (const entry of value) {
+        if (!isRecord(entry) ||
+            typeof entry.specifier !== "string" ||
+            typeof entry.fromFile !== "string" ||
+            typeof entry.reason !== "string") {
+            return INVALID_ERROR_DATA;
+        }
+        normalized.push({
+            specifier: entry.specifier,
+            fromFile: entry.fromFile,
+            reason: entry.reason,
+        });
+    }
+    return normalized;
+}
+const BUILD_PHASES = new NativeSet([
+    "parse",
+    "transform",
+    "bundle",
+    "optimize",
+    "dependency-resolution",
+    "circuit-breaker",
+    "http-bundle-validation",
+]);
+function isBuildPhase(value) {
+    return typeof value === "string" &&
+        BUILD_PHASES.has(value);
+}
+function normalizeBuildContext(value) {
+    if (!isRecord(value))
+        return INVALID_ERROR_DATA;
+    const file = optionalField(value, "file", isString);
+    const line = optionalField(value, "line", isFiniteNumber);
+    const column = optionalField(value, "column", isFiniteNumber);
+    const moduleId = optionalField(value, "moduleId", isString);
+    const phase = optionalField(value, "phase", isBuildPhase);
+    const failures = optionalField(value, "failures", isFiniteNumber);
+    const missing = optionalField(value, "missing", arrayIsArray);
+    const failed = optionalField(value, "failed", arrayIsArray);
+    const cacheDir = optionalField(value, "cacheDir", isString);
+    if (file === INVALID_ERROR_DATA ||
+        line === INVALID_ERROR_DATA ||
+        column === INVALID_ERROR_DATA ||
+        moduleId === INVALID_ERROR_DATA ||
+        phase === INVALID_ERROR_DATA ||
+        failures === INVALID_ERROR_DATA ||
+        missing === INVALID_ERROR_DATA ||
+        failed === INVALID_ERROR_DATA ||
+        cacheDir === INVALID_ERROR_DATA) {
+        return INVALID_ERROR_DATA;
+    }
+    const normalizedMissing = missing === undefined
+        ? undefined
+        : normalizeMissingDependencies(missing);
+    const normalizedFailed = failed === undefined ? undefined : normalizeStringArray(failed);
+    if (normalizedMissing === INVALID_ERROR_DATA ||
+        normalizedFailed === INVALID_ERROR_DATA) {
+        return INVALID_ERROR_DATA;
+    }
+    const normalized = {};
+    if (file !== undefined)
+        normalized.file = file;
+    if (line !== undefined)
+        normalized.line = line;
+    if (column !== undefined)
+        normalized.column = column;
+    if (moduleId !== undefined)
+        normalized.moduleId = moduleId;
+    if (phase !== undefined)
+        normalized.phase = phase;
+    if (failures !== undefined)
+        normalized.failures = failures;
+    if (normalizedMissing !== undefined)
+        normalized.missing = normalizedMissing;
+    if (normalizedFailed !== undefined)
+        normalized.failed = normalizedFailed;
+    if (cacheDir !== undefined)
+        normalized.cacheDir = cacheDir;
+    return normalized;
+}
+function normalizeHeaders(value) {
+    if (!isRecord(value))
+        return INVALID_ERROR_DATA;
+    const headers = createObject(null);
+    for (const [name, headerValue] of objectEntries(value)) {
+        if (typeof headerValue !== "string")
+            return INVALID_ERROR_DATA;
+        headers[name] = headerValue;
+    }
+    return headers;
+}
+function normalizeAPIContext(value) {
+    if (!isRecord(value))
+        return INVALID_ERROR_DATA;
+    const endpoint = optionalField(value, "endpoint", isString);
+    const method = optionalField(value, "method", isString);
+    const statusCode = optionalField(value, "statusCode", isFiniteNumber);
+    const headersValue = optionalField(value, "headers", isRecord);
+    if (endpoint === INVALID_ERROR_DATA ||
+        method === INVALID_ERROR_DATA ||
+        statusCode === INVALID_ERROR_DATA ||
+        headersValue === INVALID_ERROR_DATA) {
+        return INVALID_ERROR_DATA;
+    }
+    const headers = headersValue === undefined ? undefined : normalizeHeaders(headersValue);
+    if (headers === INVALID_ERROR_DATA)
+        return INVALID_ERROR_DATA;
+    const normalized = {};
+    if (endpoint !== undefined)
+        normalized.endpoint = endpoint;
+    if (method !== undefined)
+        normalized.method = method;
+    if (statusCode !== undefined)
+        normalized.statusCode = statusCode;
+    if (headers !== undefined)
+        normalized.headers = headers;
+    return normalized;
+}
+const RENDER_PHASES = new NativeSet([
+    "server",
+    "client",
+    "hydration",
+]);
+function isRenderPhase(value) {
+    return typeof value === "string" &&
+        RENDER_PHASES.has(value);
+}
+function normalizeRenderContext(value) {
+    if (!isRecord(value))
+        return INVALID_ERROR_DATA;
+    const component = optionalField(value, "component", isString);
+    const route = optionalField(value, "route", isString);
+    const phase = optionalField(value, "phase", isRenderPhase);
+    if (component === INVALID_ERROR_DATA ||
+        route === INVALID_ERROR_DATA ||
+        phase === INVALID_ERROR_DATA) {
+        return INVALID_ERROR_DATA;
+    }
+    const normalized = {};
+    if (component !== undefined)
+        normalized.component = component;
+    if (route !== undefined)
+        normalized.route = route;
+    if (phase !== undefined)
+        normalized.phase = phase;
+    if (hasOwn(value, "props") && value.props !== undefined) {
+        normalized.props = value.props;
+    }
+    return normalized;
+}
+function normalizeConfigContext(value) {
+    if (!isRecord(value))
+        return INVALID_ERROR_DATA;
+    const configFile = optionalField(value, "configFile", isString);
+    const field = optionalField(value, "field", isString);
+    const expected = optionalField(value, "expected", isString);
+    if (configFile === INVALID_ERROR_DATA ||
+        field === INVALID_ERROR_DATA ||
+        expected === INVALID_ERROR_DATA) {
+        return INVALID_ERROR_DATA;
+    }
+    const normalized = {};
+    if (configFile !== undefined)
+        normalized.configFile = configFile;
+    if (field !== undefined)
+        normalized.field = field;
+    if (hasOwn(value, "value") && value.value !== undefined) {
+        normalized.value = value.value;
+    }
+    if (expected !== undefined)
+        normalized.expected = expected;
+    return normalized;
+}
+function normalizeAgentContext(value) {
+    if (!isRecord(value))
+        return INVALID_ERROR_DATA;
+    const agentId = optionalField(value, "agentId", isString);
+    const intent = optionalField(value, "intent", isString);
+    const timeout = optionalField(value, "timeout", isFiniteNumber);
+    if (agentId === INVALID_ERROR_DATA ||
+        intent === INVALID_ERROR_DATA ||
+        timeout === INVALID_ERROR_DATA) {
+        return INVALID_ERROR_DATA;
+    }
+    const normalized = {};
+    if (agentId !== undefined)
+        normalized.agentId = agentId;
+    if (intent !== undefined)
+        normalized.intent = intent;
+    if (timeout !== undefined)
+        normalized.timeout = timeout;
+    return normalized;
+}
+const FILE_OPERATIONS = new NativeSet([
+    "read",
+    "write",
+    "delete",
+    "mkdir",
+]);
+function isFileOperation(value) {
+    return typeof value === "string" &&
+        FILE_OPERATIONS.has(value);
+}
+function normalizeFileContext(value) {
+    if (!isRecord(value))
+        return INVALID_ERROR_DATA;
+    const path = optionalField(value, "path", isString);
+    const operation = optionalField(value, "operation", isFileOperation);
+    const permissions = optionalField(value, "permissions", isString);
+    if (path === INVALID_ERROR_DATA ||
+        operation === INVALID_ERROR_DATA ||
+        permissions === INVALID_ERROR_DATA) {
+        return INVALID_ERROR_DATA;
+    }
+    const normalized = {};
+    if (path !== undefined)
+        normalized.path = path;
+    if (operation !== undefined)
+        normalized.operation = operation;
+    if (permissions !== undefined)
+        normalized.permissions = permissions;
+    return normalized;
+}
+function normalizeNetworkContext(value) {
+    if (!isRecord(value))
+        return INVALID_ERROR_DATA;
+    const url = optionalField(value, "url", isString);
+    const timeout = optionalField(value, "timeout", isFiniteNumber);
+    const retryCount = optionalField(value, "retryCount", isFiniteNumber);
+    if (url === INVALID_ERROR_DATA ||
+        timeout === INVALID_ERROR_DATA ||
+        retryCount === INVALID_ERROR_DATA) {
+        return INVALID_ERROR_DATA;
+    }
+    const normalized = {};
+    if (url !== undefined)
+        normalized.url = url;
+    if (timeout !== undefined)
+        normalized.timeout = timeout;
+    if (retryCount !== undefined)
+        normalized.retryCount = retryCount;
+    return normalized;
+}
+function normalizeErrorData(source) {
+    if (typeof source.message !== "string")
+        return null;
+    const message = source.message;
+    switch (source.type) {
+        case "build": {
+            const context = optionalContext(source, normalizeBuildContext);
+            if (context === INVALID_ERROR_DATA)
+                return null;
+            return context === undefined
+                ? { type: "build", message }
+                : { type: "build", message, context };
+        }
+        case "api": {
+            const context = optionalContext(source, normalizeAPIContext);
+            if (context === INVALID_ERROR_DATA)
+                return null;
+            return context === undefined ? { type: "api", message } : { type: "api", message, context };
+        }
+        case "render": {
+            const context = optionalContext(source, normalizeRenderContext);
+            if (context === INVALID_ERROR_DATA)
+                return null;
+            return context === undefined
+                ? { type: "render", message }
+                : { type: "render", message, context };
+        }
+        case "config": {
+            const context = optionalContext(source, normalizeConfigContext);
+            if (context === INVALID_ERROR_DATA)
+                return null;
+            return context === undefined
+                ? { type: "config", message }
+                : { type: "config", message, context };
+        }
+        case "agent": {
+            const context = optionalContext(source, normalizeAgentContext);
+            if (context === INVALID_ERROR_DATA)
+                return null;
+            return context === undefined
+                ? { type: "agent", message }
+                : { type: "agent", message, context };
+        }
+        case "file": {
+            const context = optionalContext(source, normalizeFileContext);
+            if (context === INVALID_ERROR_DATA)
+                return null;
+            return context === undefined ? { type: "file", message } : { type: "file", message, context };
+        }
+        case "network": {
+            const context = optionalContext(source, normalizeNetworkContext);
+            if (context === INVALID_ERROR_DATA)
+                return null;
+            return context === undefined
+                ? { type: "network", message }
+                : { type: "network", message, context };
+        }
+        case "permission": {
+            const context = optionalContext(source, normalizeFileContext);
+            if (context === INVALID_ERROR_DATA)
+                return null;
+            return context === undefined
+                ? { type: "permission", message }
+                : { type: "permission", message, context };
+        }
+        case "not_supported": {
+            const feature = optionalField(source, "feature", isString);
+            if (feature === INVALID_ERROR_DATA)
+                return null;
+            return feature === undefined
+                ? { type: "not_supported", message }
+                : { type: "not_supported", message, feature };
+        }
+        case "no_ai_available":
+            return { type: "no_ai_available", message };
+        default:
+            return null;
+    }
+}
+export function toError(veryfrontError, ErrorType = NativeError) {
+    const error = new ErrorType(veryfrontError.message);
     error.name = `VeryfrontError[${veryfrontError.type}]`;
     // Capture stack at call site, excluding toError from the trace
     // This makes debugging easier by showing where createError+toError was called
-    if (Error.captureStackTrace)
-        Error.captureStackTrace(error, toError);
-    Object.defineProperty(error, "context", {
+    if (captureStackTrace) {
+        apply(captureStackTrace, NativeError, [error, toError]);
+    }
+    defineProperty(error, "context", {
         value: veryfrontError,
         enumerable: false,
         configurable: true,
     });
     return error;
 }
-export function fromError(error) {
-    if (!error || typeof error !== "object" || !("context" in error))
+/** @internal Decode one already-extracted legacy context value. */
+export function decodeVeryfrontErrorData(contextValue, isProxy) {
+    try {
+        const context = snapshotPlainValue(contextValue, 0, {
+            isProxy,
+            seen: new NativeSet(),
+            remainingEntries: MAX_SNAPSHOT_ENTRIES,
+        });
+        if (context === SNAPSHOT_FAILED ||
+            !context ||
+            typeof context !== "object" ||
+            arrayIsArray(context)) {
+            return null;
+        }
+        return normalizeErrorData(context);
+    }
+    catch {
         return null;
-    const context = error.context;
-    if (!context || typeof context !== "object")
-        return null;
-    if (!("type" in context) || !("message" in context))
-        return null;
-    return context;
+    }
 }
 /**
  * Extract error message from any error type
  */
 export function getErrorMessage(error) {
-    if (error instanceof Error)
-        return error.message;
-    return String(error);
+    try {
+        if (isErrorInstance(error)) {
+            const message = error.message;
+            return typeof message === "string" ? message : "Unknown error";
+        }
+        return NativeString(error);
+    }
+    catch {
+        return "Unknown error";
+    }
+}
+/** Runtime-safe native Error guard for values caught from untrusted code. */
+export function isErrorInstance(error) {
+    return hasNativeErrorBrand(error);
+}
+/** Snapshot a native Error without retaining a proxy or invoking it again later. */
+export function snapshotError(error) {
+    if (!isErrorInstance(error))
+        return null;
+    return snapshotKnownError(error);
+}
+export function snapshotKnownError(error) {
+    try {
+        const descriptors = getOwnPropertyDescriptors(error);
+        const ownDataValue = (key) => {
+            const descriptor = descriptors[key];
+            return descriptor && "value" in descriptor ? descriptor.value : undefined;
+        };
+        const ownName = ownDataValue("name");
+        const ownMessage = ownDataValue("message");
+        const ownStack = ownDataValue("stack");
+        const prototype = getPrototypeOf(error);
+        const prototypeName = prototype !== null
+            ? getOwnPropertyDescriptor(prototype, "name")
+            : undefined;
+        const name = ownName === undefined &&
+            prototypeName &&
+            "value" in prototypeName &&
+            typeof prototypeName.value === "string"
+            ? prototypeName.value
+            : ownName ?? "Error";
+        const message = ownMessage === undefined ? "" : ownMessage;
+        const stack = ownStack === undefined ? undefined : ownStack;
+        if (typeof name !== "string" ||
+            typeof message !== "string" ||
+            (stack !== undefined && typeof stack !== "string")) {
+            return null;
+        }
+        return { name, message, stack };
+    }
+    catch {
+        return null;
+    }
+}
+function applySnapshotStack(error, stack) {
+    if (stack === undefined)
+        return;
+    defineProperty(error, "stack", {
+        configurable: true,
+        value: stack,
+        writable: true,
+    });
+}
+function detachVeryfrontError(snapshot) {
+    const detached = new VeryfrontError(snapshot.message, {
+        slug: snapshot.slug,
+        category: snapshot.category,
+        status: snapshot.status,
+        title: snapshot.title,
+        suggestion: snapshot.suggestion,
+        exitCode: snapshot.exitCode,
+        detail: snapshot.detail,
+        cause: snapshot.cause,
+        instance: snapshot.instance,
+        context: snapshot.context,
+    });
+    applySnapshotStack(detached, snapshot.stack);
+    return detached;
+}
+function copyOwnDataProperties(source, target) {
+    try {
+        const descriptors = getOwnPropertyDescriptors(source);
+        for (const [key, descriptor] of objectEntries(descriptors)) {
+            if (key === "name" || key === "message" || key === "stack")
+                continue;
+            if (!("value" in descriptor))
+                continue;
+            defineProperty(target, key, {
+                configurable: true,
+                enumerable: descriptor.enumerable,
+                value: descriptor.value,
+                writable: true,
+            });
+        }
+    }
+    catch {
+        // Core fields were already detached. Unreadable optional metadata is omitted.
+    }
+}
+function detachNativeError(source, snapshot) {
+    const detached = new NativeError(snapshot.message);
+    detached.name = snapshot.name;
+    applySnapshotStack(detached, snapshot.stack);
+    copyOwnDataProperties(source, detached);
+    return detached;
+}
+/**
+ * Normalize a thrown value into a detached Error snapshot.
+ *
+ * Use this at boundaries that retain or repeatedly inspect the result. A
+ * transparent Proxy can pass `instanceof Error` while throwing or changing
+ * values on a later property read.
+ */
+export function snapshotErrorAsError(error) {
+    if (isVeryfrontErrorInstance(error)) {
+        const veryfrontSnapshot = snapshotKnownVeryfrontError(error);
+        return veryfrontSnapshot
+            ? detachVeryfrontError(veryfrontSnapshot)
+            : new NativeError("Unknown error");
+    }
+    if (isErrorInstance(error)) {
+        const nativeSnapshot = snapshotKnownError(error);
+        return nativeSnapshot
+            ? detachNativeError(error, nativeSnapshot)
+            : new NativeError("Unknown error");
+    }
+    return new NativeError(safePrimitiveErrorMessage(error));
+}
+function safePrimitiveErrorMessage(error) {
+    if ((typeof error === "object" && error !== null) ||
+        typeof error === "function") {
+        return "Unknown error";
+    }
+    try {
+        return NativeString(error);
+    }
+    catch {
+        return "Unknown error";
+    }
 }
 /**
- * Ensure error is an Error instance
+ * Ensure a value is an Error while preserving the established identity
+ * contract for ordinary Error instances.
  */
 export function ensureError(error) {
-    if (error instanceof Error)
-        return error;
-    return new Error(String(error));
+    if (isErrorInstance(error)) {
+        return snapshotError(error) ? error : new NativeError("Unknown error");
+    }
+    return new NativeError(safePrimitiveErrorMessage(error));
 }