@snaptrude/plugin-core 0.6.0 → 0.7.1

package/test/errors.test.mjs

@@ -0,0 +1,184 @@
+// Node built-in test runner suite for the error module (codes/envelope/PluginError).
+// Run: node --test test/
+// Imports the BUILT package (dist) — run `pnpm build` first.
+import test from "node:test"
+import assert from "node:assert/strict"
+import {
+  PLUGIN_ERROR_CODES,
+  CODE_META,
+  isPluginErrorCode,
+  ERROR_ENVELOPE_VERSION,
+  isErrorEnvelope,
+  newErrorId,
+  PluginError,
+  PluginValidationError,
+  PluginQuotaError,
+  PluginTimeoutError,
+  PluginTransportError,
+  PluginInternalError,
+  fromEnvelope,
+  makeClientEnvelope,
+} from "../dist/index.js"
+
+const CATEGORIES = [
+  "validation", "not_found", "permission", "handle", "quota",
+  "timeout", "transport", "lifecycle", "execution", "internal",
+]
+
+function envelope(overrides = {}) {
+  return {
+    envelopeVersion: ERROR_ENVELOPE_VERSION,
+    code: "OPERATION_FAILED",
+    message: "it failed",
+    errorId: "test-id-1",
+    ...overrides,
+  }
+}
+
+// --- codes registry ---------------------------------------------------------
+
+test("every code has CODE_META with a valid category (union↔meta completeness)", () => {
+  for (const code of PLUGIN_ERROR_CODES) {
+    const meta = CODE_META[code]
+    assert.ok(meta, `missing CODE_META for ${code}`)
+    assert.ok(CATEGORIES.includes(meta.category), `bad category for ${code}: ${meta.category}`)
+  }
+  assert.equal(Object.keys(CODE_META).length, PLUGIN_ERROR_CODES.length)
+})
+
+test("codes are unique", () => {
+  assert.equal(new Set(PLUGIN_ERROR_CODES).size, PLUGIN_ERROR_CODES.length)
+})
+
+test("isPluginErrorCode narrows union members and rejects strangers", () => {
+  assert.equal(isPluginErrorCode("HANDLE_INVALID"), true)
+  assert.equal(isPluginErrorCode("TOTALLY_MADE_UP"), false)
+  assert.equal(isPluginErrorCode(""), false)
+})
+
+// --- envelope ----------------------------------------------------------------
+
+test("isErrorEnvelope accepts a minimal valid envelope", () => {
+  assert.equal(isErrorEnvelope(envelope()), true)
+})
+
+test("isErrorEnvelope accepts codes OUTSIDE the union (forward compat)", () => {
+  assert.equal(isErrorEnvelope(envelope({ code: "FUTURE_CODE" })), true)
+})
+
+test("isErrorEnvelope rejects malformed values", () => {
+  assert.equal(isErrorEnvelope(null), false)
+  assert.equal(isErrorEnvelope("boom"), false)
+  assert.equal(isErrorEnvelope({}), false)
+  assert.equal(isErrorEnvelope(envelope({ envelopeVersion: 2 })), false)
+  assert.equal(isErrorEnvelope(envelope({ errorId: undefined })), false)
+})
+
+test("newErrorId returns unique prefixed ids", () => {
+  const a = newErrorId("c-")
+  const b = newErrorId("c-")
+  assert.notEqual(a, b)
+  assert.ok(a.startsWith("c-"))
+})
+
+// --- PluginError rehydration --------------------------------------------------
+
+test("fromEnvelope picks the category sugar subclass", () => {
+  assert.ok(fromEnvelope(envelope({ code: "VALIDATION" })) instanceof PluginValidationError)
+  assert.ok(fromEnvelope(envelope({ code: "RATE_LIMITED" })) instanceof PluginQuotaError)
+  assert.ok(fromEnvelope(envelope({ code: "TIMEOUT" })) instanceof PluginTimeoutError)
+  assert.ok(fromEnvelope(envelope({ code: "TRANSPORT_LOST" })) instanceof PluginTransportError)
+  assert.ok(fromEnvelope(envelope({ code: "INTERNAL" })) instanceof PluginInternalError)
+})
+
+test("fromEnvelope preserves envelope fields on the error", () => {
+  const err = fromEnvelope(
+    envelope({
+      code: "OPERATION_FAILED",
+      details: { op: "union", handles: ["mass_1", "mass_2"] },
+      handle: "mass_1",
+      methodPath: "design.boolean.union",
+      hint: "check overlap",
+    })
+  )
+  assert.equal(err.code, "OPERATION_FAILED")
+  assert.equal(err.message, "it failed")
+  assert.equal(err.errorId, "test-id-1")
+  assert.deepEqual(err.details, { op: "union", handles: ["mass_1", "mass_2"] })
+  assert.equal(err.handle, "mass_1")
+  assert.equal(err.methodPath, "design.boolean.union")
+  assert.equal(err.hint, "check overlap")
+  assert.equal(err.category, "execution")
+})
+
+test("unknown code constructs base PluginError with code preserved verbatim", () => {
+  const err = fromEnvelope(envelope({ code: "FUTURE_CODE" }))
+  assert.equal(err.constructor, PluginError)
+  assert.equal(err.code, "FUTURE_CODE")
+  assert.equal(err.category, "internal")
+  assert.equal(PluginError.is(err), true)
+})
+
+test("hint falls back to the code's template when the envelope has none", () => {
+  const err = fromEnvelope(envelope({ code: "RATE_LIMITED" }))
+  assert.equal(err.hint, CODE_META.RATE_LIMITED.hintTemplate)
+})
+
+test("PluginError.is matches the brand across class identities (dual SDK copy)", () => {
+  // Simulate a second bundled copy: a plain object carrying the Symbol.for
+  // brand but NOT part of this module's prototype chain.
+  const impostor = Object.assign(new Error("from other copy"), {
+    [Symbol.for("snaptrude.pluginError")]: true,
+    code: "TIMEOUT",
+  })
+  assert.equal(impostor instanceof PluginError, false)
+  assert.equal(PluginError.is(impostor), true)
+  assert.equal(PluginError.is(new Error("plain")), false)
+  assert.equal(PluginError.is(null), false)
+})
+
+// --- makeClientEnvelope --------------------------------------------------------
+
+test("makeClientEnvelope mints a c- prefixed id and passes extras through", () => {
+  const env = makeClientEnvelope("TRANSPORT_LOST", "port closed", {
+    methodPath: "design.boolean.union",
+  })
+  assert.equal(isErrorEnvelope(env), true)
+  assert.equal(env.code, "TRANSPORT_LOST")
+  assert.ok(env.errorId.startsWith("c-"))
+  assert.equal(env.methodPath, "design.boolean.union")
+})
+
+// --- Registry snapshot (append-only guard) -----------------------------------
+// Deliberate: adding a code REQUIRES updating this list in the same change so
+// the addition is reviewed; removing or renaming one must fail loudly forever.
+
+test("PLUGIN_ERROR_CODES matches the reviewed snapshot (append-only contract)", () => {
+  assert.deepEqual([...PLUGIN_ERROR_CODES], [
+    "VALIDATION",
+    "INVALID_RPC_FORMAT",
+    "METHOD_NOT_FOUND",
+    "METHOD_NOT_PERMITTED",
+    "HANDLE_INVALID",
+    "HANDLE_KIND_MISMATCH",
+    "RESOURCE_QUOTA_EXCEEDED",
+    "RATE_LIMITED",
+    "PRECONDITION_FAILED",
+    "OPERATION_FAILED",
+    "TIMEOUT",
+    "CALL_TIMEOUT",
+    "TRANSPORT_LOST",
+    "PLUGIN_NOT_READY",
+    "PLUGIN_TERMINATED",
+    "RESULT_NOT_SERIALIZABLE",
+    "RESULT_TOO_LARGE",
+    "BATCH_PARTIAL",
+    "STORY_UPDATE_FAILED",
+    "STORY_HEIGHT_REJECTED",
+    "NO_ACTIVE_STRUCTURE",
+    "NO_ELIGIBLE_ELEMENTS",
+    "PROPOSAL_SWITCH_BLOCKED",
+    "INTERNAL",
+    "UNKNOWN",
+  ])
+})