@deployanyway/error-translator 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.0
+
+46 built-in definitions cover filesystem, permissions, networking, module loading, streams, HTTP response lifecycle and JavaScript errors. Each has a specific explanation, likely causes and practical checks. Rubber-duck commentary has a distinct original line for every supported definition. No commands run automatically and unknown errors remain explicitly unrecognized.
+
+```sh
+
+
+## 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.
@@ -16,3 +29,4 @@
 - Plain-English translations for ECONNREFUSED, ENOENT, EADDRINUSE, MODULE_NOT_FOUND, ERR_MODULE_NOT_FOUND, and TypeError.
 - Structured results, text rendering, and CLI with JSON output.
 - Automated tests, linting, formatting, and Node 22/24 CI.
+```

package/MIGRATION.md

@@ -0,0 +1,11 @@
+# 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.
+
+## 0.3.0 to 0.4.0
+
+46 distinct error definitions with explanations, causes and practical checks; original duck commentary for each; structured errorCatalog API and --catalog CLI.
+
+Default behavior is retained except that the expanded error catalog now recognizes additional errors. New rotation and release-plan features are opt-in.

package/README.md

@@ -1,5 +1,25 @@
 # error-translator
 
+## Browse the debugging library (0.4.0)
+
+46 built-in definitions cover filesystem, permissions, networking, module loading, streams, HTTP response lifecycle and JavaScript errors. Each has a specific explanation, likely causes and practical checks. Rubber-duck commentary has a distinct original line for every supported definition. No commands run automatically and unknown errors remain explicitly unrecognized.
+
+```sh
+npx @deployanyway/error-translator ERR_HTTP_HEADERS_SENT --mode rubber-duck
+npx @deployanyway/error-translator --catalog --json
+npx @deployanyway/error-translator --list
+```
+
+```js
+import { errorCatalog, translateError } from "@deployanyway/error-translator";
+console.log(errorCatalog({ mode: "plain" }));
+console.log(translateError({ code: "EACCES", message: "open config.json" }));
+```
+
+`errorCatalog(options?)` returns independent structured translations for the complete catalog. `--catalog` prints all guidance, or JSON with `--json`. Explicit codes still take precedence over message matching. This is a focused Node/JavaScript debugging catalog, not diagnosis of every platform or framework error. Technical reference: https://nodejs.org/api/errors.html.
+
+> **Version 0.4.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)
 
@@ -82,14 +102,54 @@ Invalid result shapes throw TypeError.
 
 ### Built-in errors
 
-| Code/name            | Guidance                                   |
-| -------------------- | ------------------------------------------ |
-| ECONNREFUSED         | Service availability, host, port, firewall |
-| ENOENT               | Missing paths and working directories      |
-| EADDRINUSE           | Port conflicts and duplicate instances     |
-| MODULE_NOT_FOUND     | CommonJS dependencies and paths            |
-| ERR_MODULE_NOT_FOUND | ES module dependencies, paths, extensions  |
-| TypeError            | Unexpected types and null/undefined values |
+| Code/name                      | Guidance                          |
+| ------------------------------ | --------------------------------- |
+| EACCES                         | Permission denied                 |
+| EPERM                          | Operation not permitted           |
+| EEXIST                         | Target already exists             |
+| ENOTDIR                        | Expected a directory              |
+| EISDIR                         | Expected a file                   |
+| ENOTEMPTY                      | Directory is not empty            |
+| EMFILE                         | Too many open files               |
+| ENFILE                         | System file table exhausted       |
+| ENOSPC                         | No space left                     |
+| EROFS                          | Read-only filesystem              |
+| EBUSY                          | Resource busy                     |
+| EXDEV                          | Cross-device operation            |
+| EPIPE                          | Broken pipe                       |
+| ECONNRESET                     | Connection reset                  |
+| ETIMEDOUT                      | Operation timed out               |
+| ENOTFOUND                      | Name lookup failed                |
+| EAI_AGAIN                      | Temporary name lookup failure     |
+| EADDRNOTAVAIL                  | Local address unavailable         |
+| ECONNABORTED                   | Connection aborted                |
+| ENETUNREACH                    | Network unreachable               |
+| EHOSTUNREACH                   | Host unreachable                  |
+| EINVAL                         | Invalid argument                  |
+| ABORT_ERR                      | Operation aborted                 |
+| ERR_INVALID_ARG_TYPE           | Wrong argument type               |
+| ERR_INVALID_ARG_VALUE          | Invalid argument value            |
+| ERR_OUT_OF_RANGE               | Value outside allowed range       |
+| ERR_HTTP_HEADERS_SENT          | Headers already sent              |
+| ERR_HTTP_INVALID_STATUS_CODE   | Invalid HTTP status               |
+| ERR_INVALID_URL                | Invalid URL                       |
+| ERR_PACKAGE_PATH_NOT_EXPORTED  | Package path not exported         |
+| ERR_PACKAGE_IMPORT_NOT_DEFINED | Package import not defined        |
+| ERR_INVALID_PACKAGE_CONFIG     | Invalid package configuration     |
+| ERR_UNKNOWN_FILE_EXTENSION     | Unknown module file extension     |
+| ERR_IMPORT_ATTRIBUTE_MISSING   | Required import attribute missing |
+| ERR_STREAM_WRITE_AFTER_END     | Write after stream end            |
+| ERR_STREAM_DESTROYED           | Stream destroyed                  |
+| ERR_SOCKET_BAD_PORT            | Invalid socket port               |
+| SyntaxError                    | Invalid JavaScript syntax         |
+| ReferenceError                 | Name is not available             |
+| RangeError                     | Value exceeds a permitted range   |
+| ECONNREFUSED                   | Connection refused                |
+| ENOENT                         | File or directory not found       |
+| EADDRINUSE                     | Address already in use            |
+| MODULE_NOT_FOUND               | Module not found                  |
+| ERR_MODULE_NOT_FOUND           | ES module not found               |
+| TypeError                      | Unexpected value type             |
 
 Translations describe likely causes, not a diagnosis. Keep the original error
 and stack trace for context. No AI API or remote service is used.
@@ -158,3 +218,44 @@ 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|rubber-duck]\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|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 {
-    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";