@deployanyway/error-translator 0.3.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.0.0
+
+- Explain This Failure: real errors and cause chains.
+- Typed API, CLI integration, runnable codebase example and meaningful workflow tests.
+- Stable contracts and migration guidance; original humor stays around accurate facts.
+
+## 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.
@@ -22,3 +35,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

@@ -3,3 +3,15 @@
 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.
+
+## 0.4.0 to stable 1.0.0
+
+diagnoseError/renderDiagnosis and diagnostic CLI flags are additive. Explicit code precedence and existing catalog/batch behavior remain. Use diagnosis.original to hand the same error to your existing handler; serializing a diagnosis omits that reference.
+
+See README for exact contracts, bounds and failure behavior.

package/README.md

@@ -1,6 +1,54 @@
 # 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.
+## Explain This Failure: real errors and cause chains (1.0.0)
+
+diagnoseError(error, options) walks actual Error.cause chains with a default eight-layer bound (maxDepth 1–32). It detects cycles, exposes unknown causes honestly and returns structured chain entries with a translation for each layer. It never throws away the original error: result.original is the exact input reference and is deliberately non-enumerable so JSON output excludes it. The caller controls rethrowing, logging and exit behavior.
+
+```js
+import { diagnoseError, renderDiagnosis } from "@deployanyway/error-translator";
+try {
+  await loadConfig();
+} catch (error) {
+  const diagnosis = diagnoseError(error, { mode: "rubber-duck" });
+  console.error(renderDiagnosis(diagnosis));
+  throw error; // preserve failure behavior and the original stack
+}
+```
+
+Options: mode plain/rubber-duck, maxDepth, includeStack (default false). Entries contain depth, name, message, optional code, translation and opt-in stack. stopped is complete/cycle/depth-limit; truncated reports incomplete traversal. Arbitrary primitive causes receive an explicit unknown translation. The caller's errors and causes are not mutated. AggregateError.errors is not flattened; this API follows the cause chain.
+
+```sh
+printf '%s' '{"message":"Config failed","cause":{"code":"ENOENT","message":"open config.json"}}' | error-translator --diagnose --json
+node node_modules/@deployanyway/error-translator/examples/explain-failure.mjs ./missing-config.json
+```
+
+--diagnose accepts a JSON error record from stdin or a quoted argument, with --max-depth and opt-in --include-stack. It rejects batch/catalog/list combinations. Translation/diagnosis exits 0; invalid input exits 2. The runnable filesystem example preserves application failure with exit 1. Messages and opt-in stacks can contain private data; this library does not redact them or run fixes.
+
+## Stable v1 contract
+
+Node 22.13+ or Node 24. MIT licensed. CLI flags, structured fields, ESM/CommonJS exports and declarations are covered by tests and installed-package checks. Existing 0.4 APIs remain available except the explicitly documented doggo-log redaction/text-context changes. Future incompatible public API changes require a major release; callers should consume structured fields rather than parse jokes. Exact humorous wording and seeded catalog choices are version-specific. No telemetry, external API keys or network service is needed for core use.
+
+Run npm test, npm run lint, npm run format:check, npm run coverage, npm run test:types and npm run verify:package from a source checkout. Runnable examples are shipped under examples/. The root demo is https://deployanyway.github.io/.
+
+## 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)
@@ -84,14 +132,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.