@deployanyway/error-translator 0.3.0 → 1.0.0

package/index.d.ts

@@ -1,5 +1,11 @@
-export type ErrorInput =
-  string | Error | { code?: string; name?: string; message?: string };
+export interface ErrorRecord {
+  code?: string;
+  name?: string;
+  message?: string;
+  stack?: string;
+  cause?: unknown;
+}
+export type ErrorInput = string | Error | ErrorRecord;
 export interface TranslationOptions {
   mode?: "plain" | "rubber-duck";
 }
@@ -21,3 +27,28 @@ export function translateErrors(
 ): Translation[];
 export function renderTranslation(result: Translation): string;
 export function listErrors(): string[];
+
+export function errorCatalog(options?: TranslationOptions): Translation[];
+export interface DiagnosisOptions extends TranslationOptions {
+  maxDepth?: number;
+  includeStack?: boolean;
+}
+export interface DiagnosticLayer {
+  depth: number;
+  name: string;
+  message: string;
+  code?: string;
+  translation: Translation;
+  stack?: string;
+}
+export interface Diagnosis {
+  readonly original: ErrorInput;
+  chain: DiagnosticLayer[];
+  stopped: "complete" | "cycle" | "depth-limit";
+  truncated: boolean;
+}
+export function diagnoseError(
+  error: ErrorInput,
+  options?: DiagnosisOptions,
+): Diagnosis;
+export function renderDiagnosis(result: Diagnosis): string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deployanyway/error-translator",
-  "version": "0.3.0",
-  "description": "Plain-English Node.js error explanations and debugging tips, because the stack trace has chosen violence.",
+  "version": "1.0.0",
+  "description": "Explain real Node.js errors and cause chains with practical debugging checks. The stack trace has chosen violence; the duck brought context.",
   "type": "module",
   "exports": {
     ".": {
@@ -27,7 +27,8 @@
     "dist",
     "index.d.ts",
     "index.d.cts",
-    "MIGRATION.md"
+    "MIGRATION.md",
+    "examples"
   ],
   "engines": {
     "node": ">=22.13"
@@ -74,7 +75,9 @@
     "plain-english",
     "typescript",
     "humor",
-    "deployanyway"
+    "deployanyway",
+    "error-cause",
+    "error-handling"
   ],
   "main": "./dist/index.cjs",
   "types": "./index.d.ts",

package/src/cli.js

@@ -6,6 +6,9 @@ import {
   renderTranslation,
   translateErrors,
   listErrors,
+  errorCatalog,
+  diagnoseError,
+  renderDiagnosis,
 } from "./index.js";
 
 import { readStdin } from "./input.js";
@@ -19,12 +22,16 @@ try {
       json: { type: "boolean" },
       batch: { type: "boolean" },
       list: { type: "boolean" },
+      catalog: { type: "boolean" },
+      diagnose: { type: "boolean" },
+      "include-stack": { type: "boolean" },
+      "max-depth": { type: "string" },
       mode: { type: "string", default: "plain" },
     },
   });
   if (values.help) {
     console.log(
-      'Usage: error-translator <error code or quoted message> [--json] [--mode plain|rubber-duck]\n\nTranslate errors into human-readable guidance. Without arguments, read stdin (256 KiB). --batch reads a JSON array of 1–100 errors. --list lists supported codes.\n\nOptions:\n  -h, --help     Show help\n  -v, --version  Show version\n  --json         Print a structured JSON result\n  --mode plain|rubber-duck   Keep useful guidance; add duck commentary\n\nExamples:\n  error-translator ECONNREFUSED\n  error-translator "TypeError: value is not a function" --json\n\nExit codes: 0 translation/help/version; 2 invalid arguments.',
+      'Usage: error-translator <error code or quoted message> [--json] [--mode plain|rubber-duck]\n\nTranslate errors into human-readable guidance. --diagnose reads a JSON error/cause record; --max-depth 1..32 bounds it; --include-stack opts into original stacks. Without arguments, read stdin (256 KiB). --batch reads a JSON array of 1–100 errors. --list lists supported codes. --catalog prints all explanations and checks.\n\nOptions:\n  -h, --help     Show help\n  -v, --version  Show version\n  --json         Print a structured JSON result\n  --mode plain|rubber-duck   Keep useful guidance; add duck commentary\n\nExamples:\n  error-translator ECONNREFUSED\n  error-translator "TypeError: value is not a function" --json\n\nExit codes: 0 translation/help/version; 2 invalid arguments.',
     );
   } else if (values.version) {
     console.log(
@@ -32,6 +39,37 @@ try {
         readFileSync(new URL("../package.json", import.meta.url), "utf8"),
       ).version,
     );
+  } else if (values.diagnose) {
+    if (values.batch || values.catalog || values.list)
+      throw new TypeError(
+        "--diagnose cannot combine with --batch, --catalog or --list.",
+      );
+    const text = positionals.length ? positionals.join(" ") : await readStdin();
+    const result = diagnoseError(JSON.parse(text), {
+      mode: values.mode,
+      includeStack: values["include-stack"] ?? false,
+      ...(values["max-depth"] !== undefined
+        ? { maxDepth: Number(values["max-depth"]) }
+        : {}),
+    });
+    console.log(
+      values.json ? JSON.stringify(result, null, 2) : renderDiagnosis(result),
+    );
+  } else if (values["include-stack"] || values["max-depth"] !== undefined) {
+    throw new TypeError("--include-stack and --max-depth require --diagnose.");
+  } else if (values.catalog) {
+    if (positionals.length || values.batch || values.list)
+      throw new TypeError(
+        "--catalog does not accept input, --batch or --list.",
+      );
+    const catalog = errorCatalog({ mode: values.mode });
+    console.log(
+      values.json
+        ? JSON.stringify(catalog, null, 2)
+        : catalog
+            .map((item) => item.code + " — " + renderTranslation(item))
+            .join("\n\n---\n\n"),
+    );
   } else if (values.list) {
     if (positionals.length || values.batch)
       throw new TypeError("--list does not accept input or --batch.");

package/src/definitions.js

@@ -1,5 +1,7 @@
+import { extraDefinitions } from "./extra-definitions.js";
 // Keep technical guidance here so contributors can add errors without changing logic.
 export const definitions = {
+  ...extraDefinitions,
   ECONNREFUSED: {
     title: "Connection refused",
     explanation:

package/src/diagnostics.js

@@ -0,0 +1,79 @@
+import { translateError, renderTranslation } from "./index.js";
+
+/** Snapshot a bounded cause chain; preserve the original without serializing it. */
+export function diagnoseError(error, options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("Options must be an object.");
+  const maxDepth = options.maxDepth ?? 8,
+    includeStack = options.includeStack ?? false;
+  if (!Number.isInteger(maxDepth) || maxDepth < 1 || maxDepth > 32)
+    throw new RangeError("maxDepth must be an integer from 1 to 32.");
+  if (typeof includeStack !== "boolean")
+    throw new TypeError("includeStack must be a boolean.");
+  // Validate the root using the established translation contract.
+  translateError(error, options);
+  const seen = new Set(),
+    chain = [];
+  let current = error,
+    stopped = "complete";
+  while (current !== undefined) {
+    if (chain.length === maxDepth) {
+      stopped = "depth-limit";
+      break;
+    }
+    if (current !== null && typeof current === "object") {
+      if (seen.has(current)) {
+        stopped = "cycle";
+        break;
+      }
+      seen.add(current);
+    }
+    const object =
+      current !== null && typeof current === "object" && !Array.isArray(current)
+        ? current
+        : undefined;
+    const raw = typeof current === "string" ? current : object?.message;
+    const message = typeof raw === "string" ? raw : String(current);
+    const name = typeof object?.name === "string" ? object.name : "Error";
+    const code = typeof object?.code === "string" ? object.code : undefined;
+    const translation = translateError(
+      { name, message, ...(code ? { code } : {}) },
+      options,
+    );
+    chain.push({
+      depth: chain.length,
+      name,
+      message,
+      ...(code ? { code } : {}),
+      translation,
+      ...(includeStack && typeof object?.stack === "string"
+        ? { stack: object.stack }
+        : {}),
+    });
+    current = object?.cause;
+  }
+  const result = { chain, stopped, truncated: stopped !== "complete" };
+  Object.defineProperty(result, "original", {
+    value: error,
+    enumerable: false,
+  });
+  return result;
+}
+export function renderDiagnosis(result) {
+  if (
+    !result ||
+    !Array.isArray(result.chain) ||
+    !result.chain.length ||
+    !["complete", "cycle", "depth-limit"].includes(result.stopped)
+  )
+    throw new TypeError("Provide a diagnosis result.");
+  return (
+    result.chain
+      .map(
+        (item, index) =>
+          `${index === 0 ? "Failure" : "Caused by"}: ${item.name}${item.code ? " [" + item.code + "]" : ""}: ${item.message}\n${renderTranslation(item.translation)}${item.stack ? "\n\nOriginal stack:\n" + item.stack : ""}`,
+      )
+      .join("\n\n---\n\n") +
+    (result.truncated ? `\n\nCause traversal stopped: ${result.stopped}.` : "")
+  );
+}