@deployanyway/error-translator 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -0,0 +1,725 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.js
+var index_exports = {};
+__export(index_exports, {
+  errorCatalog: () => errorCatalog,
+  listErrors: () => listErrors,
+  renderTranslation: () => renderTranslation,
+  translateError: () => translateError,
+  translateErrors: () => translateErrors
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/extra-definitions.js
+var extraDefinitions = {
+  EACCES: {
+    title: "Permission denied",
+    explanation: "The process lacks permission for the requested operation.",
+    likelyCauses: [
+      "A directory or file belongs to another account",
+      "The application runs under a restricted service identity"
+    ],
+    suggestions: [
+      "Check the service identity and permissions on each parent directory.",
+      "Grant only the access the application needs; avoid running everything as administrator."
+    ]
+  },
+  EPERM: {
+    title: "Operation not permitted",
+    explanation: "The operating system rejected an operation even though the target may exist.",
+    likelyCauses: [
+      "A protected resource or locked file",
+      "An operation forbidden by the current platform or identity"
+    ],
+    suggestions: [
+      "Inspect the operation, ownership and platform restrictions.",
+      "Close the process holding the resource and retry only if the operation is intended."
+    ]
+  },
+  EEXIST: {
+    title: "Target already exists",
+    explanation: "A creation operation requires a new target, but that target already exists.",
+    likelyCauses: ["A repeated initialization step", "A filename collision"],
+    suggestions: [
+      "Check the target before creating it and make initialization idempotent.",
+      "Use a distinct name rather than deleting an existing target blindly."
+    ]
+  },
+  ENOTDIR: {
+    title: "Expected a directory",
+    explanation: "A path component used as a directory is actually another kind of file.",
+    likelyCauses: [
+      "A file appears in the middle of the path",
+      "A configuration value points to the wrong target"
+    ],
+    suggestions: [
+      "Inspect each path component and its type.",
+      "Correct the directory configuration before retrying."
+    ]
+  },
+  EISDIR: {
+    title: "Expected a file",
+    explanation: "The operation received a directory where it expected a file.",
+    likelyCauses: [
+      "The filename is missing from a configured path",
+      "A directory was passed to a file operation"
+    ],
+    suggestions: [
+      "Check the complete path and inspect the target type.",
+      "Use the appropriate directory API when working with directories."
+    ]
+  },
+  ENOTEMPTY: {
+    title: "Directory is not empty",
+    explanation: "A directory operation requires an empty target, but entries remain.",
+    likelyCauses: [
+      "Generated files remain in the directory",
+      "Another process is still writing files"
+    ],
+    suggestions: [
+      "List the remaining entries and identify their owner.",
+      "Remove only confirmed disposable content or choose a new directory."
+    ]
+  },
+  EMFILE: {
+    title: "Too many open files",
+    explanation: "The process has exhausted its available file descriptors.",
+    likelyCauses: [
+      "Handles are not closed",
+      "Too many files or sockets are opened concurrently"
+    ],
+    suggestions: [
+      "Close handles in cleanup paths and bound concurrent work.",
+      "Inspect descriptor usage before considering a higher process limit."
+    ]
+  },
+  ENFILE: {
+    title: "System file table exhausted",
+    explanation: "The system cannot allocate another file handle.",
+    likelyCauses: [
+      "Many processes hold open files",
+      "The host has reached a system resource limit"
+    ],
+    suggestions: [
+      "Inspect host-wide handle usage and identify runaway processes.",
+      "Reduce concurrency and resolve leaks before changing system limits."
+    ]
+  },
+  ENOSPC: {
+    title: "No space left",
+    explanation: "The filesystem cannot allocate the space or resources required by the operation.",
+    likelyCauses: [
+      "The volume is full",
+      "Filesystem quotas or resource limits are exhausted"
+    ],
+    suggestions: [
+      "Check free space, quotas and the volume receiving the write.",
+      "Clear verified disposable data and investigate rapid growth."
+    ]
+  },
+  EROFS: {
+    title: "Read-only filesystem",
+    explanation: "The target filesystem does not permit writes.",
+    likelyCauses: [
+      "A read-only container mount",
+      "A protected or recovery-mounted volume"
+    ],
+    suggestions: [
+      "Inspect mount settings and choose an intended writable data location.",
+      "Change mount configuration only when the write is part of the deployment design."
+    ]
+  },
+  EBUSY: {
+    title: "Resource busy",
+    explanation: "A resource cannot complete the requested operation while another operation holds it.",
+    likelyCauses: [
+      "A mounted or open resource",
+      "A concurrent operation has not finished"
+    ],
+    suggestions: [
+      "Identify the process or operation holding the resource.",
+      "Wait for its completion or coordinate ownership instead of looping without a limit."
+    ]
+  },
+  EXDEV: {
+    title: "Cross-device operation",
+    explanation: "An operation such as a rename crosses filesystem boundaries that it cannot cross directly.",
+    likelyCauses: [
+      "Temporary and destination files live on different volumes",
+      "A container mount creates a filesystem boundary"
+    ],
+    suggestions: [
+      "Create temporary files on the destination filesystem when atomic rename is required.",
+      "Use an intentional copy-and-cleanup workflow when atomic movement is unnecessary."
+    ]
+  },
+  EPIPE: {
+    title: "Broken pipe",
+    explanation: "The application wrote to a stream whose receiving end has closed.",
+    likelyCauses: [
+      "A downstream command exited",
+      "A peer disconnected before the write completed"
+    ],
+    suggestions: [
+      "Handle stream errors and stop producing data when the consumer closes.",
+      "Distinguish an expected pipeline close from an unexpected connection failure."
+    ]
+  },
+  ECONNRESET: {
+    title: "Connection reset",
+    explanation: "A connection was forcibly closed while the application was using it.",
+    likelyCauses: [
+      "The remote peer closed the connection",
+      "An intermediary interrupted the session"
+    ],
+    suggestions: [
+      "Inspect peer logs, timeout settings and recent connection changes.",
+      "Retry only safe operations with a bounded backoff and avoid duplicate side effects."
+    ]
+  },
+  ETIMEDOUT: {
+    title: "Operation timed out",
+    explanation: "A connection or operation did not finish within its allowed time.",
+    likelyCauses: [
+      "An unreachable or slow peer",
+      "A timeout shorter than the expected operation"
+    ],
+    suggestions: [
+      "Check network reachability, service latency and the configured timeout.",
+      "Use bounded retries only for operations that are safe to repeat."
+    ]
+  },
+  ENOTFOUND: {
+    title: "Name lookup failed",
+    explanation: "The requested hostname could not be resolved by the lookup operation.",
+    likelyCauses: [
+      "A misspelled hostname",
+      "Resolver configuration or lookup resources failed"
+    ],
+    suggestions: [
+      "Check the exact hostname and DNS behavior from the same runtime environment.",
+      "Do not assume every lookup failure proves the hostname does not exist."
+    ]
+  },
+  EAI_AGAIN: {
+    title: "Temporary name lookup failure",
+    explanation: "Name resolution reported a temporary failure.",
+    likelyCauses: [
+      "A resolver is temporarily unavailable",
+      "A transient network or DNS problem"
+    ],
+    suggestions: [
+      "Check the resolver and network from the affected host.",
+      "Apply bounded retry with backoff and report persistent failures."
+    ]
+  },
+  EADDRNOTAVAIL: {
+    title: "Local address unavailable",
+    explanation: "The application tried to use an address that is not available on the local system.",
+    likelyCauses: [
+      "Binding to an address on another host",
+      "An interface address changed"
+    ],
+    suggestions: [
+      "Inspect local interfaces and the configured bind address.",
+      "Use the intended local interface rather than a remote destination address."
+    ]
+  },
+  ECONNABORTED: {
+    title: "Connection aborted",
+    explanation: "A connection was aborted before the operation completed.",
+    likelyCauses: [
+      "A connection failure during setup or transfer",
+      "A local or intermediary cancellation"
+    ],
+    suggestions: [
+      "Inspect the failure timing and both ends of the connection.",
+      "Handle cancellation separately from application errors when appropriate."
+    ]
+  },
+  ENETUNREACH: {
+    title: "Network unreachable",
+    explanation: "The host has no usable route to the requested network.",
+    likelyCauses: [
+      "Missing route or disconnected interface",
+      "Network isolation in a container or host"
+    ],
+    suggestions: [
+      "Inspect connectivity and routing in the application environment.",
+      "Confirm the destination network is intended to be reachable."
+    ]
+  },
+  EHOSTUNREACH: {
+    title: "Host unreachable",
+    explanation: "The destination host could not be reached through the available network path.",
+    likelyCauses: [
+      "The destination is unavailable",
+      "Routing or filtering blocks the path"
+    ],
+    suggestions: [
+      "Check the destination address and routing from the affected host.",
+      "Inspect network policy rather than disabling protection blindly."
+    ]
+  },
+  EINVAL: {
+    title: "Invalid argument",
+    explanation: "The operating system rejected an argument to the operation.",
+    likelyCauses: [
+      "A value outside the operation contract",
+      "A platform-specific unsupported value"
+    ],
+    suggestions: [
+      "Inspect the syscall and the exact values passed to it.",
+      "Validate values against the API and platform requirements."
+    ]
+  },
+  ABORT_ERR: {
+    title: "Operation aborted",
+    explanation: "An operation was cancelled through an abort mechanism.",
+    likelyCauses: [
+      "An AbortSignal was triggered",
+      "A caller timeout cancelled the operation"
+    ],
+    suggestions: [
+      "Inspect who owns the abort controller and when cancellation occurred.",
+      "Treat expected cancellation separately and clean up resources."
+    ]
+  },
+  ERR_INVALID_ARG_TYPE: {
+    title: "Wrong argument type",
+    explanation: "A Node API received an argument of the wrong type.",
+    likelyCauses: [
+      "A missing or incorrect value",
+      "An unexpected return type passed to another API"
+    ],
+    suggestions: [
+      "Read the parameter name in the error and inspect its actual value.",
+      "Validate the argument at the boundary where it enters your application."
+    ]
+  },
+  ERR_INVALID_ARG_VALUE: {
+    title: "Invalid argument value",
+    explanation: "An argument has a value the API does not accept.",
+    likelyCauses: [
+      "A valid type with an unsupported value",
+      "An invalid option combination"
+    ],
+    suggestions: [
+      "Inspect the named parameter and documented accepted values.",
+      "Validate options before calling the API."
+    ]
+  },
+  ERR_OUT_OF_RANGE: {
+    title: "Value outside allowed range",
+    explanation: "A numeric or size argument falls outside the API range.",
+    likelyCauses: [
+      "An invalid offset or length",
+      "A computed limit exceeds the supported bounds"
+    ],
+    suggestions: [
+      "Check the reported minimum and maximum and the calculation producing the value.",
+      "Add boundary tests for zero, limits and oversized input."
+    ]
+  },
+  ERR_HTTP_HEADERS_SENT: {
+    title: "Headers already sent",
+    explanation: "The server tried to change headers after the response headers had been sent.",
+    likelyCauses: [
+      "Two code paths respond to the same request",
+      "An asynchronous callback runs after the response is complete"
+    ],
+    suggestions: [
+      "Trace every response path and return after sending the response.",
+      "Coordinate asynchronous work so only one path owns the final response."
+    ]
+  },
+  ERR_HTTP_INVALID_STATUS_CODE: {
+    title: "Invalid HTTP status",
+    explanation: "The response status code is outside the accepted API range.",
+    likelyCauses: [
+      "An undefined value becomes a status",
+      "A business code is mistaken for an HTTP status"
+    ],
+    suggestions: [
+      "Check the status value before assigning or sending it.",
+      "Keep internal result codes separate from HTTP status codes."
+    ]
+  },
+  ERR_INVALID_URL: {
+    title: "Invalid URL",
+    explanation: "The URL parser cannot interpret the supplied URL.",
+    likelyCauses: [
+      "A malformed absolute URL",
+      "A relative URL without a valid base"
+    ],
+    suggestions: [
+      "Inspect the original input and supply an explicit base for relative paths.",
+      "Validate user-controlled URL inputs before making requests."
+    ]
+  },
+  ERR_PACKAGE_PATH_NOT_EXPORTED: {
+    title: "Package path not exported",
+    explanation: "A package exports map does not expose the requested subpath.",
+    likelyCauses: [
+      "Importing an internal package file",
+      "A dependency changed its public entry points"
+    ],
+    suggestions: [
+      "Inspect the package exports and use a documented public entry.",
+      "Upgrade or pin compatible dependencies instead of relying on private paths."
+    ]
+  },
+  ERR_PACKAGE_IMPORT_NOT_DEFINED: {
+    title: "Package import not defined",
+    explanation: "A package imports map has no matching internal specifier.",
+    likelyCauses: [
+      "A missing imports mapping",
+      "A specifier is used outside its intended package scope"
+    ],
+    suggestions: [
+      "Check package.json imports and the exact specifier.",
+      "Keep internal import aliases inside the package that defines them."
+    ]
+  },
+  ERR_INVALID_PACKAGE_CONFIG: {
+    title: "Invalid package configuration",
+    explanation: "Node could not use the package configuration.",
+    likelyCauses: ["Malformed package.json", "An invalid configuration field"],
+    suggestions: [
+      "Read the named package.json and validate its JSON and relevant fields.",
+      "Check the first configuration error before reinstalling dependencies."
+    ]
+  },
+  ERR_UNKNOWN_FILE_EXTENSION: {
+    title: "Unknown module file extension",
+    explanation: "The module loader does not recognize the file extension in this context.",
+    likelyCauses: [
+      "An unsupported file type is imported",
+      "The required build or loader is missing"
+    ],
+    suggestions: [
+      "Check the imported extension and the runtime module configuration.",
+      "Compile to a supported format or use a documented loader setup."
+    ]
+  },
+  ERR_IMPORT_ATTRIBUTE_MISSING: {
+    title: "Required import attribute missing",
+    explanation: "A module import requires an attribute that was not provided.",
+    likelyCauses: [
+      "A JSON import lacks the required type attribute",
+      "An import was copied from a different runtime version"
+    ],
+    suggestions: [
+      "Check the module type and import syntax for your supported Node version.",
+      "Use the required import attributes or an appropriate file-reading API."
+    ]
+  },
+  ERR_STREAM_WRITE_AFTER_END: {
+    title: "Write after stream end",
+    explanation: "Data was written after the writable stream had ended.",
+    likelyCauses: [
+      "A late callback writes to a closed stream",
+      "Multiple owners end and write the same stream"
+    ],
+    suggestions: [
+      "Trace the stream lifecycle and coordinate the writer with completion.",
+      "Test delayed callbacks and ensure end is called once work is complete."
+    ]
+  },
+  ERR_STREAM_DESTROYED: {
+    title: "Stream destroyed",
+    explanation: "An operation used a stream after it had been destroyed.",
+    likelyCauses: [
+      "A prior error destroyed the stream",
+      "Cleanup ran while work was still pending"
+    ],
+    suggestions: [
+      "Inspect the original stream error and cancellation timing.",
+      "Stop dependent work when the stream closes or is destroyed."
+    ]
+  },
+  ERR_SOCKET_BAD_PORT: {
+    title: "Invalid socket port",
+    explanation: "A socket port value is not accepted by the API.",
+    likelyCauses: [
+      "A malformed environment variable",
+      "A number outside the port range"
+    ],
+    suggestions: [
+      "Validate and parse the port configuration before creating the connection.",
+      "Do not substitute a silent default for a visibly invalid production setting."
+    ]
+  },
+  SyntaxError: {
+    title: "Invalid JavaScript syntax",
+    explanation: "The parser cannot interpret the source or input syntax.",
+    likelyCauses: [
+      "Malformed JavaScript or JSON",
+      "Syntax unsupported by the current runtime"
+    ],
+    suggestions: [
+      "Read the first reported location and inspect nearby delimiters and tokens.",
+      "Confirm the input format and runtime version before changing unrelated code."
+    ]
+  },
+  ReferenceError: {
+    title: "Name is not available",
+    explanation: "An expression refers to a binding that is not available in its current scope or initialization state.",
+    likelyCauses: [
+      "A misspelled or out-of-scope variable",
+      "Access before initialization"
+    ],
+    suggestions: [
+      "Inspect the referenced name and its scope at the reported line.",
+      "Check initialization order and add a focused regression test."
+    ]
+  },
+  RangeError: {
+    title: "Value exceeds a permitted range",
+    explanation: "An operation received a value outside its allowed range or exhausted a range-related resource.",
+    likelyCauses: [
+      "An invalid numeric size or index",
+      "Excessive recursion or allocation"
+    ],
+    suggestions: [
+      "Read the exact message to distinguish numeric bounds from stack exhaustion.",
+      "Inspect boundary values and recursion termination rather than treating every RangeError alike."
+    ]
+  }
+};
+
+// src/definitions.js
+var definitions = {
+  ...extraDefinitions,
+  ECONNREFUSED: {
+    title: "Connection refused",
+    explanation: "The application tried to connect to a service, but nothing accepted the connection.",
+    likelyCauses: [
+      "The service is not running",
+      "The host or port is incorrect",
+      "A firewall actively rejected the connection"
+    ],
+    suggestions: [
+      "Confirm that the service is running and listening on the configured host and port.",
+      "Check connection settings and firewall rules."
+    ]
+  },
+  ENOENT: {
+    title: "File or directory not found",
+    explanation: "The application tried to use a filesystem path that does not exist.",
+    likelyCauses: [
+      "The path is misspelled",
+      "The file was moved or deleted",
+      "A relative path is being resolved from an unexpected working directory"
+    ],
+    suggestions: [
+      "Check the full path and the current working directory.",
+      "Create the required file or directory if it should exist."
+    ]
+  },
+  EADDRINUSE: {
+    title: "Address already in use",
+    explanation: "The application tried to listen on an address and port that another listener already uses.",
+    likelyCauses: [
+      "Another instance of the application is running",
+      "Another service uses the same port"
+    ],
+    suggestions: [
+      "Identify the process using the port before stopping it.",
+      "Choose a different available port or stop the duplicate instance."
+    ]
+  },
+  MODULE_NOT_FOUND: {
+    title: "Module not found",
+    explanation: "Node.js could not resolve a module requested by the application.",
+    likelyCauses: [
+      "A dependency is missing",
+      "The module path is incorrect",
+      "A dependency references a missing module"
+    ],
+    suggestions: [
+      "Check the missing module name and the require stack.",
+      "Install declared dependencies with npm install and verify local paths."
+    ]
+  },
+  ERR_MODULE_NOT_FOUND: {
+    title: "ES module not found",
+    explanation: "Node.js could not resolve an imported ES module.",
+    likelyCauses: [
+      "A dependency is missing",
+      "The import path or file extension is incorrect"
+    ],
+    suggestions: [
+      "Install declared dependencies and verify the import path.",
+      "Include the file extension for relative Node.js ES module imports."
+    ]
+  },
+  TypeError: {
+    title: "Unexpected value type",
+    explanation: "An operation received a value it cannot use, such as calling a non-function or reading a property of undefined.",
+    likelyCauses: [
+      "A value is null or undefined",
+      "A value has a different type than expected"
+    ],
+    suggestions: [
+      "Inspect the value at the first relevant line in the stack trace.",
+      "Check inputs and return values before accessing properties or calling functions."
+    ]
+  }
+};
+
+// src/index.js
+var listErrors = () => Object.keys(definitions);
+function translateErrors(errors, options = {}) {
+  if (!Array.isArray(errors) || errors.length < 1 || errors.length > 100)
+    throw new RangeError("Provide 1\u2013100 errors.");
+  return Array.from(errors, (error) => translateError(error, options));
+}
+var duckLines = {
+  EACCES: "The file has a guest list. Your process is not on it.",
+  EPERM: "The operating system has declined your ambitious proposal.",
+  EEXIST: "The target is already here and has not agreed to be replaced.",
+  ENOTDIR: "That hallway is actually a cupboard.",
+  EISDIR: "You asked for one file and received the whole neighborhood.",
+  ENOTEMPTY: "The directory still has roommates.",
+  EMFILE: "Your process opened every door and forgot to close them.",
+  ENFILE: "The host has run out of chairs for file handles.",
+  ENOSPC: "The disk has eaten the final snack.",
+  EROFS: "This filesystem is a museum: look, but do not rearrange.",
+  EBUSY: "The resource is in another meeting.",
+  EXDEV: "The rename has reached the border and needs a different passport.",
+  EPIPE: "The audience left before your stream finished the speech.",
+  ECONNRESET: "The other end hung up without the usual pleasantries.",
+  ETIMEDOUT: "The operation is late and has not brought a believable excuse.",
+  ENOTFOUND: "The hostname is not answering roll call.",
+  EAI_AGAIN: "DNS requests a brief intermission, not eternal optimism.",
+  EADDRNOTAVAIL: "That address does not live on this machine.",
+  ECONNABORTED: "The connection left before the conversation was finished.",
+  ENETUNREACH: "The packet has no road to the destination.",
+  EHOSTUNREACH: "The route exists; the destination is still playing hard to reach.",
+  EINVAL: "The argument has failed the entrance interview.",
+  ABORT_ERR: "The caller pulled the emergency stop. Ask why before restarting.",
+  ERR_INVALID_ARG_TYPE: "The parameter ordered a string and received a surprise guest.",
+  ERR_INVALID_ARG_VALUE: "The type is correct. Its life choices are not.",
+  ERR_OUT_OF_RANGE: "The number wandered beyond the approved fence.",
+  ERR_HTTP_HEADERS_SENT: "The response left the station. You cannot redecorate its headers now.",
+  ERR_HTTP_INVALID_STATUS_CODE: "That number is not a useful mood for an HTTP response.",
+  ERR_INVALID_URL: "The address has syntax ambitions but no navigable destination.",
+  ERR_PACKAGE_PATH_NOT_EXPORTED: "You are trying the package staff entrance.",
+  ERR_PACKAGE_IMPORT_NOT_DEFINED: "The alias has not been introduced to this package.",
+  ERR_INVALID_PACKAGE_CONFIG: "The package instructions have become abstract art.",
+  ERR_UNKNOWN_FILE_EXTENSION: "The loader does not speak this file dialect.",
+  ERR_IMPORT_ATTRIBUTE_MISSING: "The import arrived without its required name badge.",
+  ERR_STREAM_WRITE_AFTER_END: "The stream said goodbye. Your callback is still talking.",
+  ERR_STREAM_DESTROYED: "The stream has retired. Please respect its notice.",
+  ERR_SOCKET_BAD_PORT: "The port number did not pass the harbor inspection.",
+  SyntaxError: "The parser has found punctuation with questionable intentions.",
+  ReferenceError: "That name is not available for comment in this scope.",
+  RangeError: "The value or call stack has climbed over the fence.",
+  ECONNREFUSED: "Your app knocked. The service has apparently gone for coffee.",
+  ENOENT: "The file is playing hide-and-seek. It is currently winning.",
+  EADDRINUSE: "Two servers reserved the same chair. Only one gets to sit.",
+  MODULE_NOT_FOUND: "The dependency missed roll call. Check its invitation to node_modules.",
+  ERR_MODULE_NOT_FOUND: "The module took a wrong turn. Extensions are street signs, not decorations.",
+  TypeError: "JavaScript received a surprise guest and forgot how to behave."
+};
+function translateError(error, options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("Options must be an object.");
+  }
+  const mode = options.mode ?? "plain";
+  if (!["plain", "rubber-duck"].includes(mode))
+    throw new RangeError("Supported modes: plain, rubber-duck.");
+  let code;
+  let name;
+  let message;
+  if (typeof error === "string") {
+    message = error.trim();
+  } else if (error && typeof error === "object" && !Array.isArray(error)) {
+    for (const field of ["code", "name", "message"]) {
+      if (error[field] !== void 0 && typeof error[field] !== "string") {
+        throw new TypeError(`Error ${field} must be a string.`);
+      }
+    }
+    code = error.code?.trim();
+    name = error.name?.trim();
+    message = error.message?.trim();
+  } else {
+    throw new TypeError(
+      "Provide a nonempty error string or error-like object."
+    );
+  }
+  if (!code && !name && !message)
+    throw new TypeError(
+      "Provide a nonempty error string or error-like object."
+    );
+  const matched = code || (Object.hasOwn(definitions, name ?? "") ? name : void 0) || Object.keys(definitions).find(
+    (key) => new RegExp(`\\b${key}\\b`).test(message ?? "")
+  );
+  const definition = Object.hasOwn(definitions, matched ?? "") ? definitions[matched] : void 0;
+  const fallback = {
+    title: "Unrecognized error",
+    explanation: "No built-in translation matches this error yet.",
+    likelyCauses: [],
+    suggestions: [
+      "Read the original error and inspect the first relevant line in its stack trace.",
+      "Check the documentation for the component that reported the error."
+    ]
+  };
+  const result = definition ?? fallback;
+  return {
+    code: matched ?? "UNKNOWN",
+    ...result,
+    explanation: mode === "rubber-duck" ? `${result.explanation} ${Object.hasOwn(duckLines, matched ?? "") ? duckLines[matched] : "The duck recommends investigating before blaming the compiler."}` : result.explanation,
+    likelyCauses: [...result.likelyCauses],
+    suggestions: [...result.suggestions],
+    mode
+  };
+}
+function renderTranslation(result) {
+  if (!result || typeof result.title !== "string" || typeof result.explanation !== "string" || !Array.isArray(result.likelyCauses) || !Array.isArray(result.suggestions) || ![...result.likelyCauses, ...result.suggestions].every(
+    (item) => typeof item === "string"
+  )) {
+    throw new TypeError("Provide a structured translation result.");
+  }
+  return [
+    result.title,
+    `What happened:
+${result.explanation}`,
+    ...result.likelyCauses.length ? [
+      `Likely causes:
+${result.likelyCauses.map((item) => `- ${item}`).join("\n")}`
+    ] : [],
+    ...result.suggestions.length ? [`Try:
+${result.suggestions.map((item) => `- ${item}`).join("\n")}`] : []
+  ].join("\n\n");
+}
+function errorCatalog(options = {}) {
+  return listErrors().map((code) => translateError({ code }, options));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  errorCatalog,
+  listErrors,
+  renderTranslation,
+  translateError,
+  translateErrors
+});