WIP: tighten type, validation, and causality contracts (audit response)

.changeset/r5-r10-type-and-runtime-contracts.md

@@ -0,0 +1,222 @@
+---
+'@deessejs/errors': major
+---
+
+# 2.0.0
+
+This release locks in the public surface of `@deessejs/errors`. The
+two `error()` overloads are the supported entry points; the
+constraints around `inherits`, `from`, `is`, and `causes` are
+pinned in the type system and verified by a runtime probe against
+every example in the docs.
+
+## What shipped
+
+### Two `error()` overloads
+
+The function is overloaded on whether a Standard Schema is supplied
+for `fields`. Both overloads share the same call-site shape for
+`name`, `message`, and `inherits`.
+
+```ts
+// No-schema form. The factory is callable with no arguments,
+// or with a manual generic that constrains the field shape.
+//
+//   const X = error<{ n: string }>({ name: 'X' });
+//   X({ n: 'value' }).fields.n // string
+//
+// The no-schema form accepts a string `message` (with optional
+// `{field}` placeholders) or a function `message: (data) => string`.
+const E = error({ name: 'E' });
+const instance = E();
+
+// Schema form. The factory's call signature requires the
+// schema's `InferInput` as the argument; `message` is a function
+// of the schema's `InferOutput`. A string `message` is not
+// accepted alongside a schema.
+const S = error({
+  name: 'S',
+  fields: z.object({ n: z.number() }),
+  message: (data) => String(data.n),
+});
+const s = S({ n: 1 });
+```
+
+A factory with a schema always requires its input, even for
+`z.object({})`. A no-schema factory is callable with no arguments
+when `T` defaults to `Record<string, never>`, or with the input
+required by the manual generic.
+
+### Inheritance is structural
+
+`inherits` is a static type-level relationship plus a recognition
+walk for `is()`. The leaf's `InferOutput` (or manual generic `T`)
+must be assignable to every parent's `InferOutput`; the
+constraint is enforced at the `error()` definition site. The
+walk is what makes `is()` match a child against any of its
+ancestors.
+
+```ts
+const Parent = error({
+  name: 'Parent',
+  fields: z.object({ id: z.string() }),
+  message: (d) => d.id,
+});
+const Child = error({
+  name: 'Child',
+  fields: z.object({ id: z.string(), extra: z.string() }),
+  message: (d) => `${d.id}-${d.extra}`,
+  inherits: Parent,
+}); // ok
+```
+
+`Parent.fields.id` is the only requirement the child must
+satisfy. The child may add fields but must not drop or change
+the parent's required ones. The library does not run the
+parent's schema at instantiation; the leaf's own schema is
+the only one that runs.
+
+### `.from()` builds chains, one link at a time
+
+Each `.from()` call sets the direct cause of the receiver. To
+build a chain of length N, attach each layer's cause to the
+previous one — the previous cause carries its own `.cause`.
+
+```ts
+const root = new Error('Network timeout');
+const middle = ValidationError().from(root);
+const app = AppError().from(middle);
+const chain = causes(app); // [middle, root]
+```
+
+The chain is recoverable because every link carries its own
+`.cause`; replacing the direct cause on a layer drops the
+previous link from the walk. `causes()` returns a fresh array,
+ordered immediate cause first, root cause last, with cycle
+detection.
+
+### `is()` narrows and walks
+
+`is(err, factory)` returns `true` if `err` is an instance of
+the factory, directly or through the inheritance walk. The
+factory overload narrows `err` to that factory's own
+`InferOutput`. The native-constructor overload narrows to
+`InstanceType<typeof NativeErrorClass>`.
+
+The walk consults a package-private `WeakSet` keyed on
+instance identity, in addition to the factory marker. A
+foreign object that imitates the marker slot is rejected by
+the registry check. See the Caveats for the per-load limit.
+
+## Breaking changes from 1.x
+
+- **Required input argument.** A factory declared with a
+  Standard Schema or a non-empty manual generic refuses a
+  no-arg call at compile time. Legacy call patterns
+  (`error({ name })`, `error({ name, message: 'literal' })`)
+  keep the optional argument because their default `TInput`
+  is the empty shape.
+
+- **Schema overload requires a function-form `message`.** A
+  string `message` is no longer accepted alongside a schema.
+  Consumers that relied on `{ fields: schema }` without a
+  function `message` must add one.
+
+- **Factory call signature takes the full shape, not `Partial<T>`.**
+  The 1.x signature accepted `Partial<T>` so any field could
+  be omitted. The 2.0 signature accepts `T` (or `TInput` when
+  a schema is supplied). Callers must either supply the full
+  shape or annotate fields as optional in the schema.
+
+- **The flat `causes: Error[]` field on `ErrorInstance` is gone.**
+  The previous field conflated historical `.from()` calls
+  with a true causal chain. `cause: Error | null` is now the
+  only direct field. Use the top-level `causes(error)`
+  function to walk the chain.
+
+- **`is()` is split into two overloads.** The factory
+  overload narrows to `ErrorInstance<...>`; the
+  native-constructor overload narrows to `Error` and
+  does not promise `.fields`, `.notes`, `.from()`, or
+  `.addNote()`.
+
+## Caveats
+
+- **`strictFunctionTypes` is required.** The contravariance
+  witness that enforces inheritance compatibility relies on
+  function parameters being checked contravariantly. Without
+  `strictFunctionTypes`, the inheritance constraint is
+  bypassed. `strictFunctionTypes` is enabled by `strict`,
+  which is on in this project's tsconfig.
+
+- **TypeScript 5.4 or later.** The public `error()` overloads
+  use `NoInfer<T>`, which was introduced in TypeScript 5.4.
+  Earlier versions compile but lose the `NoInfer` semantics on
+  the `T` parameter.
+
+- **Schema output must be a non-null, non-array object.** A
+  schema whose `InferOutput` is `null`, an `unknown[]`, a
+  primitive, or `undefined` is rejected at compile time via
+  the `fields: S & (IsObjectOutput<InferOutput<S>> extends true
+  ? unknown : never)` intersection, and at runtime via the
+  `isObjectFields` guard that throws `ArgsValidationError` if
+  the schema's value is malformed.
+
+- **Schemas must be synchronous.** A schema whose `validate`
+  returns a `Promise` is rejected with `ArgsValidationError`.
+  The Promise is still attached and a no-op `.catch` is added
+  so a late rejection cannot surface as an `unhandledRejection`.
+
+- **Input is required when a schema is supplied.** A factory
+  declared with a Standard Schema refuses a no-arg call at
+  compile time. The runtime also throws a localized `TypeError`
+  for the schema-bearing path so consumers who bypass the
+  type-checker still get a clear message. This applies even
+  when the schema accepts the empty shape (`z.object({})`).
+
+- **`.fields` carries the post-transform output.** For schemas
+  that transform (e.g. `z.coerce`, `z.default`, `z.transform`),
+  the leaf's `.fields` is the schema's `InferOutput`, not the
+  `InferInput`. The factory's `message` function receives the
+  post-transform output.
+
+- **`is()` is per-package-load.** An instance created by a
+  second copy of `@deessejs/errors` (a duplicate in
+  `node_modules`, a separate bundle, a CommonJS/ESM dual load,
+  two copies in a micro-frontend) is registered in *that*
+  copy's internal `INSTANCE_REGISTRY` (a `WeakSet`), not ours.
+  Holding a direct reference to its factory is not sufficient:
+  the marker slot is read and matches, but the registry check
+  fails, and `is()` returns false. To recognize cross-load
+  instances, the consumer must call `is()` from the same load
+  that produced the instance.
+
+- **The instance marker is non-writable on real instances.**
+  Set via `Object.defineProperty` with `writable: false`. A
+  foreign object that imitates the marker is rejected by the
+  registry check; a hostile object that re-defines the marker
+  on a real instance is rejected in strict mode (the
+  assignment throws) and silently fails in sloppy mode (the
+  marker is unchanged).
+
+- **The factory's `inherits` slot is a snapshot.** Built once
+  at construction, before the closure, and used for both the
+  factory's metadata and every produced instance's `inherits`.
+  The caller's array is not mutated. Classification is
+  preserved across caller-side mutations on the original
+  list.
+
+## Docs
+
+- **Public examples in `apps/web/content/docs/*.mdx` are
+  type-checked AND runtime-verified against `dist/index.d.ts`.**
+  `tests/docs-examples-typecheck.mjs` walks every fenced
+  TypeScript code block in the docs, runs `tsc --noEmit`
+  against the published types, then executes the block under
+  `node --experimental-strip-types` and verifies every
+  `console.log(...) // -> <expected>` annotation against the
+  captured stdout. A doc that announces the wrong value
+  fails the probe. As part of the audit, all MDX examples
+  were rewritten to compile, to assert the values the page
+  claims, and to build chains layer-by-layer so the
+  announced `causes(...).length` matches the walk.

.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [main, staging, dev]
 
+permissions:
+  contents: read
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
@@ -126,7 +129,8 @@ jobs:
       # directory names contain a dot (e.g. `llms.txt/route.ts`). The
       # production tsconfig does not enable it, so we run type-check:test
       # explicitly. The regular `pnpm turbo type-check` is run on the
-      # rest of the workspace by the `Type Check` job below.
+      # rest of the workspace by the `Type Check` job below. The
+      # `Type Check (Tests)` job runs the same for @deessejs/errors.
       - name: Type-check apps/web test suite
         run: pnpm --filter web type-check:test
 
@@ -167,6 +171,114 @@ jobs:
       - name: Run type check
         run: pnpm turbo type-check
 
+  # ============================================================================
+  # Type Check (Tests) — exercises the test files in @deessejs/errors
+  # ============================================================================
+  type-check-tests:
+    name: Type Check (Tests)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'pnpm'
+
+      - name: Cache Turborepo
+        uses: actions/cache@v4
+        with:
+          path: .turbo
+          key: turbo-${{ runner.os }}-${{ hashFiles('**/pnpm-lock.yaml') }}
+
+      - name: Install dependencies
+        run: pnpm install
+
+      # The standard `pnpm turbo type-check` runs `tsc --noEmit` against
+      # the source tsconfig which includes only `src/`. The
+      # `tsconfig.test.json` extends the base and includes the test
+      # files; this job catches regressions in the type-level tests
+      # that the source typecheck would silently miss.
+      - name: Run type check on tests
+        run: pnpm --filter @deessejs/errors type-check:test
+
+  # ============================================================================
+  # Consumer from dist — proves the published entry point is consumable
+  # ============================================================================
+  consumer-from-dist:
+    name: Consumer from dist
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'pnpm'
+
+      - name: Cache Turborepo
+        uses: actions/cache@v4
+        with:
+          path: .turbo
+          key: turbo-${{ runner.os }}-${{ hashFiles('**/pnpm-lock.yaml') }}
+
+      - name: Install dependencies
+        run: pnpm install
+
+      # The script builds first (tsc -p tsconfig.build.json) and
+      # then runs tests/consumer-from-dist.mjs which imports
+      # dist/index.js and exercises the public API.
+      - name: Build and run consumer smoke test
+        run: pnpm --filter @deessejs/errors test:consumer
+
+  # ============================================================================
+  # Docs examples — public example blocks in apps/web/content/docs/*.mdx
+  # must compile against the published dist/index.d.ts. The probe
+  # walks every fenced TypeScript code block, runs tsc on each in
+  # isolation, and reports drift between the docs and the public API.
+  # ============================================================================
+  docs-examples-typecheck:
+    name: Docs examples type-check
+    runs-on: ubuntu-latest
+    # Restrict the GITHUB_TOKEN to read-only; the job only
+    # checks out code and runs tsc, no write access needed.
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      # Builds first (tsc -p tsconfig.build.json), then walks
+      # the MDX code blocks in apps/web/content/docs/ and runs
+      # tsc against the published dist/index.d.ts.
+      - name: Build and type-check public examples
+        run: pnpm --filter @deessejs/errors test:docs
+
   # ============================================================================
   # Changeset required (PRs to staging only)
   # ============================================================================

.gitignore

@@ -43,5 +43,9 @@ temp/
 # Generated files
 *.tsbuildinfo
 
+# Docs examples type-check probe fixtures (generated on the
+# fly by packages/errors/tests/docs-examples-typecheck.mjs).
+packages/errors/tests/.docs-probe/
+
 # Changesets
 .changeset/