@deployanyway/error-translator 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.3.0 — 2026-10-08
+
+- Useful structured API/CLI additions described in README.
+- TypeScript declarations, CommonJS entry, coverage gates and installed archive checks.
+- Linux Node 22/24 plus Windows/macOS Node 24 CI.
+
+## 0.2.0 — 2026-10-08
+
+- Rubber-duck translations: Keep the debugging guidance, add workplace-safe rubber-duck commentary. Plain output remains the default.
+- Add npm and CI badges to the published README.
+
 ## 0.1.1 — 2026-10-08
 
 - Correct npm installation and npx documentation after the initial publication.

package/MIGRATION.md

@@ -0,0 +1,5 @@
+# 0.3.0 migration
+
+Node 22.13+ is required. Existing core APIs remain available; TypeScript declarations and CommonJS exports are new. The CLI now lives in src/cli.js behind the same executable path. Input/stdout behavior for new options is documented in README.
+
+Install 0.3.0 with npm. Seeds and exact humorous wording are version-specific. Do not treat jokes or heuristic scores as production evidence.

package/README.md

@@ -1,5 +1,10 @@
 # error-translator
 
+> **Version 0.3.0:** install from npm with Node 22.13+ or Node 24. See MIGRATION.md for changes from 0.2.0.
+
+[![npm version](https://img.shields.io/npm/v/%40deployanyway%2Ferror-translator)](https://www.npmjs.com/package/@deployanyway/error-translator)
+[![CI](https://github.com/DeployAnyway/error-translator/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/DeployAnyway/error-translator/actions/workflows/ci.yml)
+
 Plain-English Node.js error explanations and debugging tips, because the stack trace has chosen violence.
 
 ```text
@@ -70,7 +75,7 @@ An explicit code takes precedence, followed by a recognized name, then a
 case-sensitive whole-word match in the message. Unknown errors return general
 guidance with code `UNKNOWN`, or preserve an explicit unknown code.
 Invalid input throws TypeError; unsupported modes throw RangeError.
-Only `plain` is available in this MVP. Humorous modes are planned.
+Modes: `plain` (default) and `rubber-duck`, which preserves the guidance and adds commentary.
 
 ### `renderTranslation(result)`
 
@@ -95,12 +100,12 @@ and stack trace for context. No AI API or remote service is used.
 
 `error-translator <code or message> [options]`
 
-| Option            | Behavior              |
-| ----------------- | --------------------- |
-| `--help`, `-h`    | Show usage            |
-| `--version`, `-v` | Show package version  |
-| `--json`          | Print structured JSON |
-| `--mode plain`    | Select plain mode     |
+| Option            | Behavior                         |
+| ----------------- | -------------------------------- |
+| `--help`, `-h`    | Show usage                       |
+| `--version`, `-v` | Show package version             |
+| `--json`          | Print structured JSON            |
+| `--mode plain`    | Select plain or rubber-duck mode |
 
 Quote messages containing spaces or shell punctuation. Use `--` before a message
 beginning with a dash. No stdin support is included in the MVP.
@@ -141,3 +146,58 @@ are welcome.
 - [doggo-log](https://github.com/DeployAnyway/doggo-log)
 - [ship-it-meter](https://github.com/DeployAnyway/ship-it-meter)
 - [bro-say](https://github.com/DeployAnyway/bro-say)
+
+## Rubber-duck translations
+
+Keep the debugging guidance, add workplace-safe rubber-duck commentary. Plain output remains the default.
+
+```sh
+npx @deployanyway/error-translator ECONNREFUSED --mode rubber-duck
+```
+
+API (import the named functions from this package):
+
+```js
+translateError("ENOENT", { mode: "rubber-duck" });
+```
+
+## Ordered error batches and pipes
+
+```js
+import { translateErrors, listErrors } from "@deployanyway/error-translator";
+const results = translateErrors(["ENOENT", { code: "ECONNREFUSED" }], {
+  mode: "rubber-duck",
+});
+console.log(results[0].suggestions);
+console.log(listErrors());
+```
+
+Batches accept 1–100 errors in order, fail on malformed entries and return independent arrays. This is deterministic guidance, not diagnosis. Unknown errors remain unknown: keep the original stack.
+
+```sh
+echo "ECONNREFUSED" | node bin/cli.js --mode rubber-duck
+node bin/cli.js --batch --json < errors.json
+node bin/cli.js --list --json
+```
+
+Without arguments, read UTF-8 stdin (maximum 256 KiB). Arguments take precedence. --batch expects a JSON array; --json emits an array of results. --list catalogs supported codes. Status 0 means translated, including unknown errors; status 2 means invalid input.
+
+## Run from source
+
+```sh
+git clone --branch main https://github.com/DeployAnyway/error-translator.git
+cd error-translator
+npm ci
+npm run build
+node bin/cli.js --help
+```
+
+## Candidate quality standard
+
+Version 0.3 provides useful declaration types, ESM/CommonJS exports, installed-archive checks, and coverage gates (90% statements/lines/functions, 85% branches). CI covers Linux Node 22/24 and Windows/macOS Node 24. Node 22.13+ is required. No runtime dependencies, telemetry or network requests.
+
+From a source checkout: npm ci, npm run build, npm run coverage, npm run test:types, npm run verify:package. Pack verification installs a temporary local archive and checks module entries, types, executable and offline npm exec.
+
+[Contribution guide](CONTRIBUTING.md) · [Conduct](CODE_OF_CONDUCT.md) · [Security](SECURITY.md) · [Roadmap](ROADMAP.md) · [Migration](MIGRATION.md).
+
+**Tools for developers who probably know better.** Software nobody requested, built with questionable priorities, and shipped with absolute confidence!

package/bin/cli.js

@@ -1,38 +1,2 @@
 #!/usr/bin/env node
-import { parseArgs } from "node:util";
-import { URL } from "node:url";
-import { readFileSync } from "node:fs";
-import { translateError, renderTranslation } from "../src/index.js";
-
-try {
-  const { values, positionals } = parseArgs({
-    allowPositionals: true,
-    options: {
-      help: { type: "boolean", short: "h" },
-      version: { type: "boolean", short: "v" },
-      json: { type: "boolean" },
-      mode: { type: "string", default: "plain" },
-    },
-  });
-  if (values.help) {
-    console.log(
-      'Usage: error-translator <error code or quoted message> [--json] [--mode plain]\n\nTranslate errors into human-readable guidance.\n\nOptions:\n  -h, --help     Show help\n  -v, --version  Show version\n  --json         Print a structured JSON result\n  --mode plain   Translation mode (MVP: plain only)\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(
-      JSON.parse(
-        readFileSync(new URL("../package.json", import.meta.url), "utf8"),
-      ).version,
-    );
-  } else {
-    const result = translateError(positionals.join(" "), { mode: values.mode });
-    console.log(
-      values.json ? JSON.stringify(result, null, 2) : renderTranslation(result),
-    );
-  }
-} catch (error) {
-  console.error(
-    `error-translator: ${error.message}\nRun with --help for usage.`,
-  );
-  process.exitCode = 2;
-}
+import "../src/cli.js";

package/dist/index.cjs

@@ -0,0 +1,201 @@
+"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, {
+  listErrors: () => listErrors,
+  renderTranslation: () => renderTranslation,
+  translateError: () => translateError,
+  translateErrors: () => translateErrors
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/definitions.js
+var definitions = {
+  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 = {
+  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");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  listErrors,
+  renderTranslation,
+  translateError,
+  translateErrors
+});

package/index.d.cts

@@ -0,0 +1,23 @@
+export type ErrorInput =
+  string | Error | { code?: string; name?: string; message?: string };
+export interface TranslationOptions {
+  mode?: "plain" | "rubber-duck";
+}
+export interface Translation {
+  code: string;
+  title: string;
+  explanation: string;
+  likelyCauses: string[];
+  suggestions: string[];
+  mode: "plain" | "rubber-duck";
+}
+export function translateError(
+  error: ErrorInput,
+  options?: TranslationOptions,
+): Translation;
+export function translateErrors(
+  errors: ErrorInput[],
+  options?: TranslationOptions,
+): Translation[];
+export function renderTranslation(result: Translation): string;
+export function listErrors(): string[];

package/index.d.ts

@@ -0,0 +1,23 @@
+export type ErrorInput =
+  string | Error | { code?: string; name?: string; message?: string };
+export interface TranslationOptions {
+  mode?: "plain" | "rubber-duck";
+}
+export interface Translation {
+  code: string;
+  title: string;
+  explanation: string;
+  likelyCauses: string[];
+  suggestions: string[];
+  mode: "plain" | "rubber-duck";
+}
+export function translateError(
+  error: ErrorInput,
+  options?: TranslationOptions,
+): Translation;
+export function translateErrors(
+  errors: ErrorInput[],
+  options?: TranslationOptions,
+): Translation[];
+export function renderTranslation(result: Translation): string;
+export function listErrors(): string[];

package/package.json

@@ -1,9 +1,20 @@
 {
   "name": "@deployanyway/error-translator",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Plain-English Node.js error explanations and debugging tips, because the stack trace has chosen violence.",
   "type": "module",
-  "exports": "./src/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./src/index.js"
+      },
+      "require": {
+        "types": "./index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
   "bin": {
     "error-translator": "./bin/cli.js"
   },
@@ -12,16 +23,26 @@
     "bin",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "dist",
+    "index.d.ts",
+    "index.d.cts",
+    "MIGRATION.md"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.13"
   },
   "scripts": {
-    "test": "node --test",
+    "test": "node --test test/*.test.js",
     "lint": "eslint .",
     "format": "prettier --write .",
-    "format:check": "prettier --check ."
+    "format:check": "prettier --check .",
+    "build": "node scripts/build.mjs",
+    "pretest": "npm run build",
+    "prepack": "npm run build",
+    "coverage": "c8 --all --include=src/**/*.js --reporter=text --reporter=json-summary --reporter=lcov --check-coverage --lines=90 --statements=90 --functions=90 --branches=85 node --test test/*.test.js",
+    "test:types": "tsc -p tsconfig.json",
+    "verify:package": "node scripts/verify-package.mjs"
   },
   "repository": {
     "type": "git",
@@ -35,8 +56,12 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/node": "^26.6.4",
+    "c8": "^12.0.0",
+    "esbuild": "^0.28.2",
     "eslint": "^10.12.0",
-    "prettier": "^3.6.2"
+    "prettier": "^3.6.2",
+    "typescript": "^7.0.2"
   },
   "keywords": [
     "nodejs",
@@ -46,6 +71,12 @@
     "debugging",
     "error-messages",
     "error-translator",
-    "plain-english"
-  ]
+    "plain-english",
+    "typescript",
+    "humor",
+    "deployanyway"
+  ],
+  "main": "./dist/index.cjs",
+  "types": "./index.d.ts",
+  "homepage": "https://deployanyway.github.io/"
 }

package/src/cli.js

@@ -0,0 +1,59 @@
+import { parseArgs } from "node:util";
+import { URL } from "node:url";
+import { readFileSync } from "node:fs";
+import {
+  translateError,
+  renderTranslation,
+  translateErrors,
+  listErrors,
+} from "./index.js";
+
+import { readStdin } from "./input.js";
+
+try {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+      json: { type: "boolean" },
+      batch: { type: "boolean" },
+      list: { type: "boolean" },
+      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.',
+    );
+  } else if (values.version) {
+    console.log(
+      JSON.parse(
+        readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+      ).version,
+    );
+  } else if (values.list) {
+    if (positionals.length || values.batch)
+      throw new TypeError("--list does not accept input or --batch.");
+    console.log(
+      values.json ? JSON.stringify(listErrors()) : listErrors().join("\n"),
+    );
+  } else {
+    const text = positionals.length ? positionals.join(" ") : await readStdin();
+    const result = values.batch
+      ? translateErrors(JSON.parse(text), { mode: values.mode })
+      : translateError(text, { mode: values.mode });
+    console.log(
+      values.json
+        ? JSON.stringify(result, null, 2)
+        : Array.isArray(result)
+          ? result.map(renderTranslation).join("\n\n---\n\n")
+          : renderTranslation(result),
+    );
+  }
+} catch (error) {
+  console.error(
+    `error-translator: ${error.message}\nRun with --help for usage.`,
+  );
+  process.exitCode = 2;
+}

package/src/index.js

@@ -1,10 +1,28 @@
 import { definitions } from "./definitions.js";
+export const listErrors = () => Object.keys(definitions);
+
+/** Translate an ordered, bounded batch without mutating input. */
+export function translateErrors(errors, options = {}) {
+  if (!Array.isArray(errors) || errors.length < 1 || errors.length > 100)
+    throw new RangeError("Provide 1–100 errors.");
+  return Array.from(errors, (error) => translateError(error, options));
+}
+const duckLines = {
+  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.",
+};
 
 /**
  * Translate a nonempty string, Error, or error-like object with a code/name/message.
  * Explicit codes take precedence over names and message matching.
  * @param {string | Error | {code?: string, name?: string, message?: string}} error
- * @param {{mode?: 'plain'}} [options]
+ * @param {{mode?: 'plain' | 'rubber-duck'}} [options]
  * @returns {{code: string, title: string, explanation: string, likelyCauses: string[], suggestions: string[], mode: string}}
  */
 export function translateError(error, options = {}) {
@@ -12,7 +30,8 @@ export function translateError(error, options = {}) {
     throw new TypeError("Options must be an object.");
   }
   const mode = options.mode ?? "plain";
-  if (mode !== "plain") throw new RangeError("Supported modes: plain.");
+  if (!["plain", "rubber-duck"].includes(mode))
+    throw new RangeError("Supported modes: plain, rubber-duck.");
   let code;
   let name;
   let message;
@@ -58,6 +77,10 @@ export function translateError(error, options = {}) {
   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,

package/src/input.js

@@ -0,0 +1,15 @@
+/** Read bounded UTF-8 stdin without swallowing upstream failures. */
+export async function readStdin(stream = process.stdin) {
+  if (stream.isTTY) throw new TypeError("Pipe or redirect input.");
+  let size = 0;
+  const chunks = [];
+  for await (const chunk of stream) {
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+    size += buffer.length;
+    if (size > 262144) throw new RangeError("stdin exceeds 256 KiB.");
+    chunks.push(buffer);
+  }
+  const text = Buffer.concat(chunks).toString("utf8").trim();
+  if (!text) throw new TypeError("Provide nonempty input.");
+  return text;
+}