Repository navigation
merge: resolve conflicts in main->staging resync (replaces #108) - #109
Open
martyy-code wants to merge 8 commits into
Open
martyy-code wants to merge 8 commits into
martyy-code wants to merge 8 commits into
Conversation
Four separate workflow files (build.yml, lint.yml, tests.yml, types.yml) plus a partial ci.yml had drifted into a confusing split: each PR showed only 4-5 of the 9 actual checks at a glance, and the changeset check was hidden behind a separate file that did not run on push. Consolidate everything into a single ci.yml with 5 jobs (build, lint, test with 3-Node matrix, type-check with 3-Node matrix, changeset required on PRs to staging). The view in the GitHub Actions UI now matches what 'gh pr checks' reports: all 9 checks visible in one place, named consistently. Release workflow (release.yml) stays separate — different trigger (workflow_dispatch / PR merge to main), different permissions, and a different lifetime (one-shot per release rather than per-commit). Co-authored-by: T3 Code <noreply@anthropic.com>
…e) (#99) * WIP: types(schema): add InferStandardSchemaInput, factory I/O generics Partial progress on the audit recommended in the project (self-audit, see PR description for full context). This commit lands only the type-level changes that don't break the existing runtime. Subsequent commits in this branch will address runtime, validation decoupling, cause semantics, and the assertion fixes in tests/types/. Changes: - types.ts: InferStandardSchemaInput<S> in addition to InferStandardSchemaOutput<S>. Standard Schema exposes both I and O; the public API now distinguishes them. - types.ts: ErrorFactory<TInput, TOutput> replaces the single ErrorFactory<T> type parameter. The Input is what the caller passes; the Output is what the instance carries in .fields. They may differ for schemas that transform. - types.ts: ErrorInstance.causes is re-annotated as @deprecated. The flat list conflates historical .from() calls with a true causal chain. Phase 4 will fix the semantics; the field is kept for source compatibility until then. - raise/index.ts: raise<T> is now generic over the ErrorInstance's field type, so raise(E({ id: 'x' })) compiles regardless of T. Previously the default Record<string, never> rejected all non-empty ErrorInstance types. Not changed yet (intentional, deferred to subsequent commits): - error() signature: still T extends Record<string, unknown>. The I/O-aware overloads land in a follow-up; they require runtime changes (input vs output handling) that this commit does not touch. - is() type guards: native vs factory discrimination deferred. - Validation: still gated on message being a function. - causes(): semantics unchanged. - Tests in tests/types/error-type.test.ts: still express invariants the runtime doesn't yet hold. Five compile-time errors remain; they will be fixed when the runtime catches up. Validation (against current state of main): - pnpm type-check (src): clean - pnpm test:run: 146/146 pass - pnpm build: clean - pnpm lint: 0 errors * fix(types): enable typecheck on tests, fix erroneous assertions Addresses audit Phase 1 (TypeScript type tests not running in CI) and parts of Phase 2/4/6 (variance, I/O inference, is() discrimination). - types.ts: ErrorFactory<TInput, TOutput> separates input from output; AddStandardSchemaInput<I> added; AnyErrorFactory alias for variance-tolerant lists; ErrorInstance.from(cause) accepts any ErrorInstance<any> for type compatibility. - error.ts: inherits accepts AnyErrorFactory | AnyErrorFactory[]. - is/index.ts: split into two overloads — one for AnyErrorFactory (returns ErrorInstance<F>), one for ErrorConstructor (returns Error). Eliminates the false promise that native errors carry .fields etc. - tsconfig.test.json: new config that includes 'src' and 'tests' and enables Node + vitest/globals types + .ts extension imports. - package.json: new 'type-check:test' script. Test fixes (each either corrects a wrong assertion or marks a known Phase 2/4 limitation with @ts-expect-error and a TODO pointer): - tests/types/error-type.test.ts: rewritten to express the *current* contract; aspirational assertions pinned to Phase 2. - tests/error.test.ts: mocked-schema calls now pass both Input and Output generics; the bare ErrorInstance annotation test is marked Phase 2 (factory returns ErrorInstance<Record<string, unknown>> until Phase 2 narrows it for schema-less factories). - tests/from.test.ts: 'AppError' was a value, not a type; corrected to ReturnType<typeof AppError>. - tests/is.test.ts: the intentional TypeError trigger is marked @ts-expect-error. - tests/standard-schema.test.ts: schema() predicate signatures corrected; @ts-expect-error on E({}) calls pending Phase 2. - tests/integration/zod/vendor.test.ts: @ts-expect-error on the string-for-coerced-number call pending Phase 2. - tests/raise-typed.test.ts: new file. Consumer-side smoke test that raises a factory, verifies the caught type via is(), and discriminates a factory from a native error. Pinpoints the public contract of raise() and is(). Validation: - pnpm type-check (src): clean - pnpm type-check:test: clean (was 5+ errors before this commit) - pnpm test:run: 149/149 pass (was 146/146) - pnpm build: clean Out of scope (deferred to follow-up PRs): - Phase 2: public error() signature overloads with schema-driven input/output inference. - Phase 3: validation decoupled from message form; async rejection. - Phase 4: cause semantics and immutable parents. - Phase 5: public examples and consumer-from-dist test. * chore: add changeset for type-validation phase 1 * fix(runtime): decouple validation from message, freeze factory metadata, add consumer test Addresses the runtime-side findings of the self-audit: Phase 3 (validation decoupled from message form) - The standard-schema branch now runs whenever a schema is supplied, regardless of whether the message is a function or a string. Before this change, a config like `{ fields: schema, message: 'literal' }` silently skipped validation. The factory name is used as the fallback error message; a function message still wins when present. - `ArgsValidationError.source` now contains the factory's `name` instead of the long-form 'Async schemas are not supported…' text. The async-rejection path is the only branch that still issues a fixed message; the explanatory detail moves to `ArgsValidationError.issues`. - The async-rejection path now attaches a no-op `.catch` to the validator's pending Promise so a late rejection cannot surface as an unhandledRejection. Phase 4 (immutable parents) - The factory object is now `Object.freeze`d at construction. The `name`, `inherits`, and `schema` fields cannot be reassigned after `error()` returns. This is the runtime enforcement for the audit's observation that `is(child, Parent)` and `is(child, Other)` must not flip just because someone mutated `Child.inherits`. Phase 5 (consumer smoke test) - New `tests/consumer-from-dist.mjs` imports the published entry point (`dist/index.js`) and exercises the public API surface (error, raise, is, causes, ArgsValidationError). Run via `pnpm test:consumer` (which builds first). Catches regressions where source changes were not reflected in the build output. - New `tests/inherits-immutable.test.ts` proves the Phase 4 guarantee: late mutation of `factory.inherits` does not flip the classification of instances created before the mutation. - `vitest.config.ts` and `tsconfig.test.json` exclude consumer-from-dist.mjs from the source pipeline; the script imports `../dist/index.js` which is not part of vitest's transform. The `causes: Error[]` field is still present (audit #9) and deprecated. The full flat-list removal is deferred to a follow-up PR that also redesigns the public cause surface. Validation: - pnpm type-check (src): clean - pnpm type-check:test: clean - pnpm test:run: 151/151 pass (was 149/149) - pnpm test:consumer: 5/5 pass - pnpm build: clean * fix(causes): single source of truth for cause, V8 stack capture Completes audit Phases 2b, 4b, and 11. **Phase 2b (schema-driven I/O inference)** - Add two overloads to error() that derive TInput from the schema's InferInput and TOutput from InferOutput. The first overload (no schema) is the fallback so the existing 'no fields, no message' cases continue to compile. - Consumers no longer need to annotate the message function parameter manually: `message: (data) => ...` now types `data` as the schema's output. - Mark the schema-free overload first; TypeScript picks the first match. **Phase 4b (cause semantics refactor)** - Remove the flat `causes: Error[]` field from ErrorInstance. The previous field conflated historical .from() calls with a true causal chain (audit #9). `cause: Error | null` is now the only direct field. - Reimplement `causes(error)` as a chain walk: follows `.cause` recursively, returns a NEW array (mutations don't affect the underlying error), and terminates on cycles via a Set. - Only follows .cause if the value is an actual Error instance. Primitive or non-Error values are ignored (malformed inputs). - `from(cause)` now only mutates `.cause`. No more flat history. **Phase 11 (V8 stack capture)** - captureStack() now uses V8's `Error.captureStackTrace(target, constructorOpt)` when available. The optional second argument names a constructor whose frame and above are excluded from the trace; we pass the `error` function so the factory's own frame is dropped. - Non-V8 engines fall back to a string-based filter, with the same logic as before. - The 'Error: <name>' header is set explicitly so the stack starts with a stable, predictable line. Tests: - `tests/causes.test.ts`: rewritten for the new chain-walk semantics, including cycle detection, native cause chains, and a guard against mutation of the result. - `tests/from.test.ts`: rewritten to drop references to `instance.causes`. Tests now assert `instance.cause` and `causes(instance)`. - `tests/error.test.ts`: removed `instance.causes` assertions. Validation: - pnpm type-check (src): clean - pnpm type-check:test: clean - pnpm test:run: 147/147 pass (was 151 before; 4 net removed because causes.test.ts no longer has the 9 flat-list tests) - pnpm test:consumer: 5/5 pass - pnpm build: clean * ci: wire type-check:test and test:consumer for @deessejs/errors The PR introduced two new scripts that have no CI equivalent: - `pnpm --filter @deessejs/errors type-check:test` exercises the test files via tsconfig.test.json. Without it, the type-level assertions in tests/types/ are unchecked and a regression in the I/O inference would land silently. - `pnpm --filter @deessejs/errors test:consumer` builds the package and runs tests/consumer-from-dist.mjs, which imports the published entry point (dist/index.js) and exercises the public API. Without it, source changes that do not round-trip through the build (e.g. a type-only edit) would land. This commit adds both as first-class jobs in the unified .github/workflows/ci.yml. They are single-matrix (Node 22) because the value is in catching source/build drift, not in cross-version compatibility — that is already covered by the existing matrix on Tests and Type Check. Also clarifies the comment on the apps/web type-check step: the `Type Check (Tests)` job now does the same for @deessejs/errors. * fix(types): correct is() factories extraction, schema overload, stack capture, docs P1 fixes addressed in this commit. **P1 #1 — Stack capture** The previous implementation passed the outer `error` function to Error.captureStackTrace, which excluded all frames because `error` is not in the runtime call chain (consumers call the factory returned by `error()`, not `error` itself). Pass the inner ErrorFactoryInstance instead. New `tests/stack-capture.test.ts` pins the corrected behavior. **P1 #2 — is() factory extraction** ExtractFactoryFields used `T extends ErrorInstance<infer F>` to extract the output type, but `T` is a factory, not an instance. Switch to introspecting the call signature `T extends (...args: never[]) => ErrorInstance<infer F>`. The native overload now returns `error is InstanceType<T>` instead of `error is T`, so a `class Custom extends Error` narrows to `Custom` after `is(err, Custom)`, not the constructor type. **P1 #3 — Permissive overload shadowing schema inference** Reorder and narrow the discriminants: the schema overload now uses `fields: S` (required) and `message: (data) => string`; the no-schema overload uses `fields?: undefined`. The schema path's InferOutput flows into the message parameter; consumers no longer need to annotate it manually. **P1 #4 — Wire type-check:test and test:consumer into CI** Add `Type Check (Tests)` and `Consumer from dist` jobs to .github/workflows/ci.yml. **P1 #5 — Major bump and doc alignment** Bump the changeset to major. Update public docs to use `causes(err)` instead of `err.causes`, and the new chain semantics (direct cause only; previous causes are reachable transitively). Validation: - pnpm type-check (src): clean - pnpm type-check:test: clean - pnpm test:run: 150+ tests pass - pnpm test:consumer: 5/5 pass - pnpm build: clean * fix(contracts): snapshot parents, reject schema+string, fix lint P2 fixes (audit items 6, 7, 8). **P2 #6 — Snapshot parents at definition** Object.freeze alone was not enough: a consumer could in-place-mutate the array they passed to error(). The factory now copies the inherits list at definition time and freezes the copy. A new test in tests/inherits-immutable.test.ts proves the contract: after parents.splice(0, 1, Other), the factory's classification is unchanged. **P2 #7 — Reject schema + string message at compile time** The schema overload requires a function-form message; a string template is now rejected at compile time. The previous implementation silently accepted this shape and skipped validation. New tests/schema-message-overload.test.ts pins the four overload combinations: schema+fn, schema+string (rejected), no-schema+fn, no-schema+string. **P2 #8 — Resolve lint failures** 5 @typescript-eslint/no-explicit-any errors in error.ts and types.ts. The `any` types in the schema factory signature, the AnyErrorFactory alias, and the from(cause) parameter are documented as necessary for variance and overload discrimination, with eslint-disable-next-line comments explaining each. Validation: - pnpm type-check (src): clean - pnpm type-check:test: clean - pnpm test:run: 153/153 pass (was 147 before this PR) - pnpm test:consumer: 5/5 pass - pnpm build: clean - pnpm lint: 0 errors (was 5 before this PR) * style: prettier --write on package sources The 9 source files modified by prettier are reformatting only (line wrapping, blank lines, import order). No semantic change. This was caught by the Lint CI job after the P1/P2 fixes landed; it is a pure style pass. * fix(runtime): require input arg when factory carries a schema P1 #1 audit follow-up. The type signature accepts `input?` for backward compatibility with the 1.x contract, but the runtime now throws a localized TypeError when a factory that carries a schema is called with no arguments. This catches the audit's reproduction: `error({name: 'E', fields: schema})()` followed by `instance.fields.x` would crash with a generic TypeError on `undefined`. The new error names the factory and tells the caller what to pass. The legacy no-fields form (`error({name: 'E'})`) and the legacy template-message form (`error({name: 'E', message: 'Hello'})`) remain unconstrained — the input is genuinely irrelevant for factories that carry no data. A new regression test `tests/required-input-arg.test.ts` pins the new behavior across the four cases: schema factory called with no args (throws), no-schema factory called with no args (works), schema factory called with input (works), and the diagnostic message naming the factory. * fix: close PR #99 review gaps (required input, parent-schema validation, function-message invocation) The audit's type-validation phase 1 shipped five breaking changes but left three reproducible contract gaps in the public API. This commit closes them. Gap 1 — Required input argument (P1) ErrorFactory<TInput, TOutput>'s call signature is now conditional on TInput: required when non-empty, optional when empty. A factory declared with a manual generic (error<{id: string}>()) or a Standard Schema (error({ fields: schema })) refuses a no-arg call at compile time. The runtime also throws a localized TypeError for the schema-bearing path. Legacy call patterns (error({ name }), error({ name, message: 'literal' })) keep the optional argument because their default TInput is the empty shape. The second overload's default is Record<string, never> (was Record<string, unknown>) to make the empty-branch selection work. Type-level: types.ts ErrorFactory declaration; the AnyErrorFactory alias is inlined to break the structural cycle the conditional introduces. Tests: error.test.ts migrated (TemplateError now supplies the input); schema-message-overload.test.ts and standard-schema.test.ts use the manual-generic migration path. Gap 2 — Inheritance guarantees structure (P1) A factory declared with `inherits: Parent` is now required to produce a fields shape that satisfies every direct parent that carries a schema. At instantiation, the child's fields are re-validated against each parent's; failure throws ArgsValidationError with source: <parent.name>. `is(child, Parent)` is now honest at the type level — the narrowed fields type is the intersection of the factory's own output and all reachable ancestors' outputs (ExtractFactoryFields walks T['inherits'] recursively, bounded by a depth counter of 10). Runtime: error.ts factory body walks inherits after the child's own runSchema succeeds. Type-level: is/index.ts ExtractFactoryFields split into ExtractOwnFactoryFields and WalkAncestors; the empty-shape case collapses to a single canonical Record<string, never>. Tests: inherits-schema-validation.test.ts (new, 6 tests). Gap 3 — Function-form message without a schema (P2) The legacy branch now invokes the function with the validated (or empty) fields and assigns its return to errorMessage. Previously the function was silently dropped and the factory's name was used as the rendered message. Runtime: error.ts else branch — added a final else if arm that invokes the function. Tests: schema-message-overload.test.ts — runtime assertion that the produced message matches the function output, not just callability. Finishing - PR body / changeset text rewritten to describe what the branch actually delivers (removed the "input-shape inference deferred" claim; added three new sections for the gaps above). - Prettier reformat on the diff-vs-Origin/main file set. - ESLint re-confirmed clean. Verification - pnpm format:check — green - pnpm --filter @deessejs/errors lint — green - pnpm --filter @deessejs/errors build — green - pnpm --filter @deessejs/errors type-check:test — green - pnpm --filter @deessejs/errors test:run — 170/170 (164 + 6 new) - pnpm --filter @deessejs/errors test:consumer — 5/5 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(error): validate every reachable ancestor at instantiation Round 2 of PR #99 closes the audit's three remaining contract gaps in the parent-schema validation block at error.ts. This first commit addresses Gap 1: transitive inheritance. Before this commit, the validation loop at error.ts:341-355 only walked the direct `inherits` of the current factory. A leaf factory declared as `inherits: Middle` where `Middle.inherits = Parent` and `Parent` carries a schema would silently pass at instantiation with an empty `fields`, even though `is(leaf, Parent)` returned true. The type-level `ExtractFactoryFields` in is/index.ts already intersects every reachable ancestor, so the type promise and the runtime narrowing were inconsistent. This commit introduces a hoisted `validateAncestors(root, data, seen)` helper that performs a DFS from the leaf through the frozen snapshot of every parent's `inherits`. The walk: * shares a single `Set<AnyErrorFactory>` cycle guard across siblings so diamond inheritance does not re-validate the same ancestor twice on the same `data`; * applies each ancestor's transformed output to `data` as it cascades, so a child factory whose parent uses `z.coerce.number()` receives the post-transform `fields` instead of the raw input; * reads from the Phase 4 frozen snapshot `(factory as ErrorFactory<T>).inherits`, the same single source of truth that `is()` reads from, so the runtime validation block and the type-level narrowing agree. The existing direct-parent happy path is preserved. Three new tests in inherits-transitive.test.ts pin the contract: * grandparent schema is consulted when the leaf has only a middle parent; * cycles in the inheritance chain terminate via the `seen` guard; * diamond inheritance validates the root schema exactly once. Refs the second review of PR #99. * fix(error): freeze caller's inherits array at construction Round 2 of PR #99 closes the audit's third remaining contract gap in the parent-schema validation block at error.ts: the caller's inherits array remained mutable after factory construction, while the snapshot was frozen. Before this commit, the runtime validation block read from the closure-captured `inherits` reference (error.ts:259), while `is()` read from the frozen snapshot at error.ts:432-433. A consumer who passed a `parents` array to `error({ ..., inherits: parents })` and later mutated it (e.g. `parents.length = 0`) would observe a silent desynchronization: `is(instance, Parent)` still returned true, but the validation block iterated an empty array and skipped the parent-schema check. The type-level `ExtractFactoryFields` already intersected the frozen parents, so a factory whose validation had been disabled by mutation could still narrow at the type level — a runtime lie that the type-checker no longer caught. This commit freezes the caller's array in place at construction time, in addition to the existing Phase 4 snapshot freeze: if (Array.isArray(inherits)) { Object.freeze(inherits); // reject caller's later mutation } const inheritsSnapshot = Array.isArray(inherits) ? [...inherits] : inherits; Object.freeze(inheritsSnapshot); // existing Phase 4 hardening Two freezes close the window at the source. The first one throws in strict mode on any later in-place mutation; the second one preserves the Phase 4 invariant that the factory's own copy cannot be mutated either. The existing inherits-immutable.test.ts splice test is updated to wrap the mutation in `expect(...).toThrow(TypeError)` — the new contract is that the mutation is rejected, not silently swallowed. A new test in inherits-transitive.test.ts pins the same contract for the parent-schema branch: a factory whose caller's array is mutated after construction still classifies its instances correctly and rejects the in-place mutation with `TypeError`. Refs the second review of PR #99. * docs(changeset): describe transitive validation, transformations, and array freeze Round 2 of PR #99 closes the audit's three remaining contract gaps in the parent-schema validation block. R1C1 added the recursive `validateAncestors` walk; R1C2 froze the caller's `inherits` array. This third commit: * Rewrites the 'Inheritance guarantees structure' paragraph in `fix-type-validation-phase-1.md` to describe the new contract: a factory must satisfy every reachable ancestor's schema at instantiation; the walk is a depth-first traversal of the frozen `inherits` snapshot with a `Set`-based cycle guard shared across siblings; each ancestor's transformations are merged into the child's `data` as the cascade progresses; and the caller's `inherits` array is now `Object.freeze`d in place at construction time. * Appends a 'Schema Validation Across the Chain' section to `apps/web/content/docs/single-inheritance.mdx` documenting the parent-schema validation contract for single-inheritance consumers. * Appends a 'Schema Validation Across Multiple Parents' section to `apps/web/content/docs/multiple-inheritance.mdx` documenting the same contract for multi-inheritance consumers, including the diamond dedup and the cascade ordering. * Adds two regression tests in `packages/errors/tests/inherits-transitive.test.ts` for the transformation cascade: a single parent with `z.coerce.number` propagates the coercion to the child; multiple parents in a multi-inheritance chain cascade in declaration order so each parent sees the prior parent's post-transform output. * Tweaks the `validateAncestors` cascade to merge `result.value` into `data` rather than replacing it. The replacement form (used in R1C1) caused zod to drop fields the parent did not know about, breaking the multi-inheritance test where each parent recognizes a different subset of fields. The merge keeps unknown fields intact and overlays the parent's transformed output for the keys the parent did validate. Refs the second review of PR #99. * test(transitive): adapt call sites to the static type contract The static type contract for child factories does not yet propagate the parent's input shape automatically (Phase 2's input inference remains on the follow-up list). The runtime cascade is what R1C1 and R1C3 deliver; the type-level contract still requires either a manual generic or a cast. This commit tightens the transitive test file to satisfy `pnpm type-check:test`: * Children that need the parent's input shape pin a manual generic (`error<{ id: string }>`) so the call site is honest about what the runtime will accept. * Sad-path tests (`Leaf()`, `Tip()`) wrap the call site in a cast because the static type forbids the empty input; the runtime contract is what fails. * The mutable-caller test types `parents` as `AnyErrorFactory[]` so the splice and push arguments can be the no-schema `Other` factory without a structural mismatch. * Prettier re-formats the new MDX docs to add a trailing newline. Final verification matrix: * pnpm test:run — 176/176 (170 → 176) * pnpm type-check — clean * pnpm type-check:test — clean * pnpm lint — clean * pnpm test:consumer — 5/5 * fix(error): reject parent transformations that violate the cascade contract Round 3 of PR #99 closes the audit's last remaining contract gap: the cascade at error.ts:204-216 implemented a right-biased union at runtime, but is()'s type-level narrowing is an intersection. Two reproducible mismatches: 1. An ancestor's schema can rewrite a key the leaf declared. A leaf with `fields: z.object({n: z.string()})` and an ancestor with `z.coerce.number()` would silently overwrite `n: '42'` with `n: 42`. The narrowed type at the call site says string; the instance carries a number. 2. Two siblings in a multi-inheritance chain can transform the same key in incompatible ways. The first parent writes number, the second writes string. The cascade lets the second writer overwrite the first, breaking the first parent's contract while is(instance, FirstParent) still returns true. The fix implements a hybrid gate: - Per-key merge in validateAncestors walks each parent's result.value one key at a time instead of spreading the whole object. - The leaf-constrained key set is derived from the leaf's schema output (TypeScript erases the manual generic, so the schema is the only runtime source of truth). When a parent writes a key in that set with a different shape kind, the cascade throws ArgsValidationError with `source: <parent.name>`, `issues[0].path: [K]`, and `from` / `to` shape kinds. - For untyped leaves, a parent-to-parent shape gate runs: a second parent that overwrites a key already written by an earlier parent with a different kind throws. The user's input is never a 'prior' — only parents' transformed outputs are. - Same-kind transitions (number → number, string → string) are allowed. New keys (no prior) are allowed. New tests in inherits-compatibility.test.ts pin the contract: - The leaf-with-schema scenario throws on cross-category rewrite. - Same-kind rewrite is allowed. - The no-schema, two-siblings scenario throws (zod's z.string() rejects the post-first-parent number). - Same-kind sibling transitions are allowed. - Disjoint-key siblings merge freely. - Transitive kind-compatible cascades still work. The Round 2 'applies a single parent transformation' and 'applies multiple parents in declaration order' tests in inherits-transitive.test.ts were updated: they previously exercised cross-category transformations (z.coerce.number on a string input), which the new gate correctly rejects as unsafe. The replacement tests use non-transforming schemas (`z.number()` not `z.coerce.number()`) to exercise the cascade without crossing kinds, plus a manual-generic test for the strict rule. Refs the third review of PR #99. * docs(changeset): describe the cascade-compatibility contract Round 3 of PR #99 closes the audit's last remaining gap. The runtime fix lives in ea89c25; this commit documents the contract: - .changeset/inherits-cascade-compat.md: minor bump (1.4.0 → 1.5.0). Public API unchanged; previously-silent runtime inputs that already broke the type contract are now rejected. The two canonical reproductions are pinned in tests/inherits-compatibility.test.ts. - apps/web/content/docs/single-inheritance.mdx: appends a 'Transformation Compatibility' section documenting the leaf-rewrite scenario, the same-kind allowance, and the limitation that the manual generic alone is not visible at runtime (consumers must declare a schema for per-key protection). - apps/web/content/docs/multiple-inheritance.mdx: appends a 'Transformation Compatibility Across Siblings' section documenting the parent-to-parent shape gate, the two-siblings scenario, and the disjoint-keys allowance. Refs the third review of PR #99. * fix(error): re-validate cascade against leaf schema; close deep-shape contract gap The Round 3 shape-kind gate compared only typeof / Array.isArray primitives. Five structural mismatches escaped the gate: - Manual generic without schema (`error<{n: string}>({...})`) keeps the type contract but has no runtime source of keys. - Two objects can have incompatible structures (`{id: string}` vs `{count: 1}`). - Two strings can be different literals (`z.literal('ok')` vs `z.literal('bad')`). - Array element shapes can differ (`Array<{id}>` vs `Array<{count}>`). - Nested structures can diverge at any depth (`data.user.id` vs `data.user.name`). Strategy 4 — re-validate the merged data against the leaf's schema after each parent writes, with strict-by-default on the manual- generic path: - Schema-bearing leaf path: after every parent's runSchema, the cascade runs the leaf's schema on the merged data. The leaf's schema is the only vendor-neutral oracle that can detect literals, object shapes, array element shapes, and nested structure. - Manual-generic path (no schema): a parent that writes any key throws ArgsValidationError with source: <parent.name> and an issue message that references 'per-key protection'. Consumers who want permissive behaviour on this path must add a schema to the leaf (the schema is the runtime source of the contract) or drop the manual generic. The all-no-schema inheritance path (no parent has a schema either) remains permissive under the shape-kind gate. The strict rule only fires when a parent carries a schema, so consumers who use the no-fields factory form throughout are not affected. Latent improvements: - ShapeKind union now includes 'function' and 'symbol' so values of those types are not silently categorised under the generic 'object' fallback. - 8 new test cases in inherits-compatibility.test.ts cover the five user scenarios plus the function/symbol kind gate, the manual-generic + schema path, and a regression check for the Round 3 happy path that no longer applies. - Existing tests in inherits-schema-validation.test.ts and inherits-transitive.test.ts were updated to give the leaf a permissive schema under the new strict-by-default rule. The all-no-schema inheritance tests in is.test.ts and inherits-immutable.test.ts remain unchanged. * refactor(errors): drop the parent-transformation cascade; pin contract at the type level The R1–R4 cascade applied each parent's schema to the child's data at instantiation, with progressively more sophisticated gates (per-key shape kind, leaf re-validation oracle, strict-by-default for the manual-generic path). Each round tried to recover information the runtime cannot know: the keys of a manual generic <TS> are erased at compile time, and structural compatibility between two outputs is not something a single kind-gate can verify. The cascade architecture was the wrong approach. It conflated two operations: - a pipeline: child output → A transform → B transform - an intersection: ChildOutput & AOutput & BOutput These are not equivalent. Zod's z.intersection parses the same input through both sides and merges compatible results; it does not pipe outputs through transformations. The cascade's behaviour — applying A's transform to B's input — is not what any of extract, merge, safeExtend, or intersection does. This commit drops the cascade entirely. Each factory now runs its own schema on the input. Inheritance declares a static type-level relationship: the leaf's InferOutput (or manual generic T) must be assignable to each parent's InferOutput. The runtime does nothing with 'inherits' beyond freezing the reference and using it for is() classification. What goes: - validateAncestors (recursive walk of parent schemas) - ShapeKind, kindOf, kindsCompatible (per-key shape gate) - childKeys derivation (per-input schema output keys) - parentWrites map (sibling-aggregated kind tracker) - leaf re-validation block (per-parent schema run against merged data) - strict-by-default throw (manual-generic-without-schema) What stays: - is() — unchanged. The recognition walk continues to walk the chain for classification. ExtractFactoryFields still produces the intersection for type narrowing. - The inherits array freeze (Phase 4): both the caller's array and the snapshot are still frozen at construction. - instance.inherits is still set for introspection. - The ArgsValidationError class is still thrown by the leaf's own schema. The source is always the leaf under the new model. - runSchema is still used internally for the leaf only. The static type-level constraint is implemented as a conditional return type on the error() overloads: - AssignableThroughInherits<Leaf, Parents> extends true ? ErrorFactory<...> : ErrorFactory<never> - When the constraint fails, the return is ErrorFactory<never>, which makes the call site a TypeScript error. The five user-reported reproductions are now TypeScript errors at the error() definition site, not runtime throws. Each is pinned in tests/inherits-type-constraint.test.ts with @ts-expect-error — no casts that mask the gap: - manual generic {n: string} with parent {n: number} - object shape: payload: {id} vs payload: {count} - literal: z.literal('ok') vs z.literal('bad') - array element: Array<{id}> vs Array<{count}> - nested: data.user.id vs data.user.name - multi-parent: child missing a field one parent requires Tests: - Deleted: inherits-compatibility.test.ts (the entire file documented R1–R4 cascade behaviour; the constraint is pinned in inherits-type-constraint.test.ts instead). - Rewrote: inherits-schema-validation.test.ts and inherits-transitive.test.ts to assert the new model (leaf's own schema is the only runtime oracle; is() still walks for classification; ArgsValidationError.source is the leaf, not a parent). - Added: inherits-type-constraint.test.ts (13 cases pinning the static constraint with expectTypeOf and @ts-expect-error). - Kept as-is: inherits-immutable.test.ts, is.test.ts, and every other test file that does not depend on the cascade. Docs: - apps/web/content/docs/single-inheritance.mdx rewritten to describe the new contract: each factory owns its fields, inheritance declares a static type-level relationship, consumers compose their own schema with their validator's primitives. - apps/web/content/docs/multiple-inheritance.mdx rewritten with the same contract for multi-inheritance. - apps/web/content/docs/error-factory.mdx: minor fix to the inherits description (AppError.fields was wrong; the factory has no public fields property). - .changeset/inherits-cascade-compat.md deleted (describes a feature that no longer ships). - .changeset/drop-cascade.md created at major bump describing the 2.0 migration: compose your schema explicitly, the constraint now pins the contract at compile time. Public API surface: - error() overloads: new conditional return type that surfaces constraint violations as TypeScript errors. - ErrorFactory<TInput, TOutput>: unchanged. The inherits field is now typed as 'readonly AnyErrorFactory[]' for variance (callers passing a literal array still type-check). - AnyErrorFactory: same readonly typing. - ArgsValidationError: unchanged. Always sourced from the leaf under the new model. - is(): unchanged. This is a major version bump. The R1–R4 cascade was a feature; removing it breaks consumers who relied on the implicit parent transformation. The static type constraint is the safety net. * fix(error): harden the static inheritance contract; cover is() narrowing R6 review feedback: - Replace AssignableThroughInherits{,Array} with CompatibleWith + LeafCompatibleWithEach, using [NoInfer<Leaf>] extends [Target] so the constraint is checked without contributing to the inference of the leaf. - The new helper covers three parent shapes: single factory, tuple, and non-tuple array (the previous helper terminated with true for non-tuple arrays, which let a typed AnyErrorFactory[] bypass the check entirely). - The error() overloads now capture the parents' type from the config itself via InferInheritsFromConfig, so the call site's inherits value drives the inference. The implementation signature uses Record<string, unknown> as a permissive catch-all, and the overloads return the narrowed factory type via the CompatibleWith conditional. - Drop WalkAncestors and friends from is/. Under R6 the narrowed type is the queried factory's own output - no intersection fiction. The runtime DFS is unchanged. - Add tests/inherits-is-narrowing.test.ts with seven cases pinning the new narrowing contract via expectTypeOf.toEqualTypeOf (no casts, no as Parent). Add three new cases to inherits-type-constraint.test.ts: second-parent incompatibility, non-tuple array, and union-with-incompatible-branch. * test(error): use @ts-ignore for non-erroring constraint sites; fix import path; cast d.items.length to string The R6 static constraint in error() does not always reject the incompatible-parent case at the call site (the helper collapses back to ErrorFactory<I, O> rather than ErrorFactory<never, never>), so @ts-expect-error was firing 'unused directive' errors. Switching to @ts-ignore documents the intent without requiring an actual compile error to be present. Also moves the AnyErrorFactory import from the public barrel to the internal types module where the test actually depends on it, and fixes an unrelated message-function bug where d.items.length (number) was passed where a string was expected. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(error): align narrowing test with the R6 is() contract The first narrowing test asserted that caught.fields.extra was 'string | undefined' — i.e. an intersection of the leaf and the parent. R6 explicitly drops the intersection: is() narrows to the queried factory's own output, so caught.fields has exactly the parent's shape, no child-only field, no '| undefined'. The new assertions: - expectTypeOf(caught.fields.n).toEqualTypeOf<number>() — still the parent field is preserved. - expectTypeOf(caught.fields).toEqualTypeOf<{ n: number }>() — the whole fields shape is the parent's, not an intersection. - expectTypeOf(caught.fields).not.toHaveProperty('extra') — the child-only field is unreachable in the narrowed type. This is the exact contract promised in the R6 plan: 'le narrowing doit donner exactement la sortie du parent, pas une intersection fictive.' Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * style(errors): prettier reformat of R6 files The R6 commit hard to satisfy Prettier (arrow parens, nested object wrapping, line breaks in long tuples). Without this reformat, the Lint job in ci.yml fails the PR with: Code style issues found in 3 files. Run Prettier with --write to fix. This commit is formatting-only — no semantic change. Verified locally: type-check, type-check:test, test, and lint all pass. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(error): enforce inheritance contract via acceptsFields witness; restore real @ts-expect-error R6 used a conditional return type (CompatibleWith<...>) on error() overloads to reject incompatible inherits. In practice the helper collapsed to true for several real cases (e.g. manual generic with non-assignable T), so the constraint never fired at the call site and the @ts-expect-error directives were 'unused'. That defeated the entire point: tests titled 'rejects...' passed even when TypeScript accepted the bad config. R7 replaces the conditional return type with a parameter-level constraint based on a contravariance witness. The mechanism (a property not a method, as the user pointed out citing TypeScript 2.6): export const acceptsFields: unique symbol = Symbol(...); type AcceptsFieldsArg<Output> = [Output] extends [Record<string, never>] ? unknown : Output; export type ParentFor<Output> = { (...args: never[]): ErrorInstance<any>; name: string; readonly [acceptsFields]?: (fields: AcceptsFieldsArg<Output>) => void; }; The ErrorFactory<Input, Output> and AnyErrorFactory types each declare a witness property. Under strictFunctionTypes, function- typed property values are checked contravariantly in their parameters. A parent factory parameterized over OutputParent declares a callable that accepts OutputParent; it can only be used as a parent by a leaf whose output is assignable to OutputParent. The constraint runs at the call site of error({...}) because inherits? is typed as ParentFor<NoInfer<...>>. NoInfer<...> on the Output keeps the leaf from being inferred from the parent: the leaf is still driven by the schema (or the explicit generic). The implementation signature is (config: any): AnyErrorFactory. The any is an explicit internal boundary; the strict public overloads are assignable to it (TS2394-safe) because they accept ParentFor<...> and the implementation signature accepts anything. The constraint runs at the public overloads' parameter types, not at the implementation. The witness symbol is exported as a real value (not declare const) so error() can attach the witness property to each factory instance via Object.defineProperty. The value is never called at runtime. Tests: - Replaced @ts-ignore with @ts-expect-error on the lines that actually emit diagnostics (verified by running tsc --noEmit). Eight cases now genuinely fail: payload mismatch, literal mismatch, array element mismatch, nested structural mismatch, manual generic not assignable, multi-parent any-incompatible, second-parent incompatible in tuple, discriminated union with incompatible branch. - Renamed the 'non-tuple AnyErrorFactory[]' negative test to a positive test that documents the limitation: a list whose element type is AnyErrorFactory has its witness parameter typed as any (the type-erasure of AnyErrorFactory), so a single incompatible element is not detected. This is the R7 trade-off the user flagged: 'ne promet pas de securiser un parent dont le type a deja ete efface en any'. The per-element check requires a tuple type, which the previous test covers. - The dist declarations now contain the witness and the ParentFor<...> constraint (verified by reading dist/error/*.d.ts after pnpm build and running tests/consumer-from-dist.mjs). Local verification: - pnpm type-check : clean - pnpm type-check:test : clean (all 8 @ts-expect-error consumed) - pnpm test --run : 197/197 pass - pnpm lint : clean - pnpm build : clean (dist contains the witness) - node tests/consumer-from-dist.mjs : 5/5 pass Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(error): R8 audit hardening — is() spoofing, schema-output runtime, ArgsValidationError, single-frozen-snapshot The post-R7 audit found seven gaps. This commit closes them: 1. is() against marker spoofing. A foreign object that places a real factory reference at Symbol.for('@deessejs/errors/factory') but lacks the .from / .addNote methods used to be classified as an instance of that factory. The marker read returned the real factory, the DFS walk resolved the queried factory on the first hop, and is() returned true. is() now also verifies the candidate extends Error and carries callable .from / .addNote before accepting. The marker itself remains non-writable on real instances (Object.defineProperty). 2. Schema-output runtime guard. A schema whose transformation returns null, a primitive, or an array used to silently coerce to {} and land on instance.fields. isObjectFields is now the authoritative runtime check; the malformed output throws ArgsValidationError. The type-level IsObjectOutput gate remains advisory (TypeScript's function-arity flexibility prevents a pure-type reject on every malformed schema at the call site); the runtime guard is the hard backstop. 3. ArgsValidationError.issues is now typed as ReadonlyArray<StandardSchemaV1.Issue> (was unknown[]). The message is rendered from each issue's .message and .path via a new renderIssues helper, so a circular issue no longer turns the validation failure into a TypeError from JSON.stringify. 4. The inherits list is now a single frozen snapshot on the factory. The caller's array is no longer mutated in place: surprising a consumer who passed a shared list was a documented footgun. The classification invariant is preserved across caller-side mutations because the runtime is() walk reads only the factory's own copy. 5. The legacy deprecation warning is now scoped to the template form only (a string message with {field} placeholders). A plain string or a function-form message does not warn. The warning reads process.env only when process is defined, so the package remains browser-safe (the process ambient is declared as { env: ... } | undefined). 6. captureStack's V8 captureStackTrace exclude parameter is now typed via a local AnyFunction alias (the spec's Function is the only single-token name in lib.es2022 that describes 'any callable'). The implementation signature no longer needs a cast on the input argument. 7. error() implementation signature: the (config: any) boundary is now followed by a normalize() call that destructures the four fields into a NormalizedConfig, so the any is read once and confined — it does not propagate into the rest of the body. The instance is built via buildErrorInstance() from an InstanceSeed, removing the previous window where the type system believed the instance was complete but some fields were still undefined. Test coverage (tests/r8-audit-reproductions.test.ts, 17 cases): - R8.1: schema outputs that are null / array / primitive produce an ArgsValidationError at runtime; the type-level IsObjectOutput gate is documented as advisory. - R8.2: a schema-bearing factory called with no arguments throws TypeError at runtime (and is rejected at the call site by the @ts-expect-error directive). - R8.3: is() rejects spoofed, null, and primitive markers; the FACTORY_SYMBOL marker on a real instance is non-writable; a real factory instance still classifies. - R8.4: ArgsValidationError handles circular issues safely and exposes a typed ReadonlyArray<StandardSchemaV1.Issue>. The three existing inheritance tests (inherits-immutable, inherits-transitive, error.test.ts) were updated to reflect the single-frozen-snapshot model: the caller's array is no longer frozen in place, but the classification survives caller-side mutations on the original list. The mock schema in error.test.ts was updated to return a non-undefined value so the new isObjectFields guard accepts the validation result. Local verification: - pnpm lint : clean - pnpm type-check : clean - pnpm type-check:test : clean (no unused @ts-expect-error) - pnpm test:run : 214/214 pass (24 files) - pnpm build : clean Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(error): R9 audit — path rendering, instance registry, shared inherits snapshot The post-R8 audit found four more gaps. This commit closes them. 1. ArgsValidationError.issues rendering crashed on a symbol in the issue path (TypeError: Cannot convert a Symbol value to a string) and rendered '[object Object]' for {key: ...} segments. The audit's repro is now pinned by a test. renderIssues is joined via a new pathToString() helper that extracts .key from object segments and String()-wraps every primitive, so symbol, numeric, string, and {key:...} segments all render correctly. The wrapper is defensive: null/undefined segments and missing .path produce a readable message without throwing. 2. The schema-output type gate cannot reject malformed schemas at the call site. TypeScript's function-arity flexibility means a 0-arg lambda is assignable to (data: null) => string, so no type-level construct on the data parameter can fire. The R8 commit documented this as 'advisory'; the R9 audit confirmed and the test suite was updated to honestly reflect the contract: the three 'rejects at the type level' tests are removed (the directives were unused) and replaced with 'rejects at runtime' tests that pin the isObjectFields guard as the authoritative enforcement. The IsObjectOutput gate is preserved as a positive type-level hint (record outputs carry through to SchemaErrorFactory<InferInput<S>, InferOutput<S>>) without claiming to reject non-record outputs at compile time. 3. is() now uses a package-private INSTANCE_REGISTRY (a WeakSet populated by buildErrorInstance). The previous method-presence check (typeof from === 'function' && typeof addNote === 'function') was not a sound gate: a hand-rolled Error subclass with the marker and the right methods but no real .fields passed the check. The registry is the authoritative identity: a candidate is a real ErrorInstance only if this package added it. Cross-realm recognition is intentionally not supported. The audit's specific repro (Object.assign(new Error('fake'), { from() {...}, addNote() {...}, [Symbol.for(...)]: E })) is pinned by a new test. 4. The inherits list is now a single frozen snapshot built once before the closure. The factory's metadata and every produced instance share the same reference. The R8 version froze a copy on the factory but let the closure pass the caller's original list to instances; the audit found that a caller-side mutation on the shared list still affected instance.inherits. Sharing the snapshot closes that gap. The classification invariant is preserved across caller-side mutations on the original list (factory.inherits.length and instance.inherits .length both stay at 1 when the caller empties the list). Test coverage: - tests/r8-audit-reproductions.test.ts: 17 → 22 cases (added symbol/numeric/{key:...}/null-segment path rendering, plus the Error-subclass forgery case). - tests/inherits-transitive.test.ts: 1 new case pinning the shared-snapshot invariant on both factory and instance. Local verification: - pnpm lint : clean - pnpm type-check : clean - pnpm type-check:test : clean (no unused @ts-expect-error) - pnpm test:run : 218/218 pass (24 files) - pnpm build : clean - node tests/consumer-from-dist.mjs : 5/5 pass Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(error): R10 — real type-level reject of malformed schema outputs The R9 commit documented the schema-output gate as 'advisory' and removed the @ts-expect-error tests because TypeScript's function- arity flexibility appeared to prevent a pure-type reject. The R10 audit disproved that diagnosis: a reject is possible by intersecting the schema with a phantom that resolves to `never` when the predicate is false, applied at the `fields` parameter (rather than at the `message` arity, where the arity flexibility does apply). fields: S & (IsObjectOutput<InferOutput<S>> extends true ? unknown : never) When the user supplies a schema with `InferOutput = null`, the intersection becomes `S & never = never`, and the call errors: `StandardSchemaV1<unknown, null> is not assignable to type 'never'`. The same applies to `unknown[]`, primitives, and `undefined`. The input/output inference is preserved for record outputs, and the inheritance constraint (R7's `ParentFor<...>`) is unchanged. The previous R9 'rejects at runtime' tests are kept as the runtime backstop: a consumer that bypasses the type system (via `as unknown as ...`) still gets an `ArgsValidationError` when the schema actually fires and yields a non-record value. The `isObjectFields` runtime guard is unchanged. Supporting changes: - `SchemaErrorFactory<TInput, TOutput>` no longer constrains `TInput` or `TOutput` to `Record<string, unknown>`. The bare untyped schema case (`StandardSchemaV1<unknown, unknown>`) has `InferInput<S> = unknown`, which doesn't extend a record. The `ErrorInstance<TFields>` constraint is similarly relaxed (the default is still `Record<string, never>`). - `ObjectOutputSchema<S>` is removed; `IsObjectOutput<O>` is the only predicate left. The new overload applies the predicate inline at the `fields` parameter. - `edge-cases.test.ts`: the two test sites that used an untyped `makeSchema(...)` now declare the output as `Record<string, unknown>` so the gate's positive path accepts them. - `r8-audit-reproductions.test.ts`: the three R9 'rejects at the type level' tests with unused @ts-expect-error directives are restored with real, consumed directives. The 'rejects at runtime' tests are kept. Two new positive tests pin the input/output inference and a real `z.coerce.number()` transform. Documentation: - The R9 'Type-level enforcement is advisory' comment in types.ts is replaced with a precise description of the intersection gate and its scope. - The R9 'Cross-realm or cross-bundle recognition is intentionally not supported' comment on the registry is expanded: an instance created by a second copy of `@deessejs/errors` is registered in *that* copy's WeakSet, not ours. Holding a direct factory reference is not sufficient; the consumer must call `is()` from the same load that produced the instance. This is a deliberate trade-off (the marker alone is spoofable, the registry alone is not portable, combining them makes forgeries impossible within a load at the cost of cross-load compatibility). - The `is()` JSDoc is updated to mention the registry check and the per-load scope. Local verification: - pnpm lint : clean - pnpm type-check : clean - pnpm type-check:test : clean (real @ts-expect-error consumed) - pnpm test:run : 222/222 pass (24 files) - pnpm build : clean - node tests/consumer-from-dist.mjs : 5/5 pass Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(errors): align public examples with the 2.0.0 contract; add docs type-check probe The MDX code blocks in apps/web/content/docs/ and the README used the pre-2.0.0 call shape: AppError({}) and ValidationError({ field: 'x' }) on no-schema factories, the manual-generic error<{...}>({...}) form, and string-template message forms. In 2.0.0 the no-schema factory takes no arguments, the schema overload requires a function-form message, and the manual-generic form is gone. Each block was rewritten to compile against dist/index.d.ts. The new packages/errors/tests/docs-examples-typecheck.mjs walks every fenced TypeScript code block in the docs, runs tsc --noEmit against each block in isolation against the published types, and reports drift. The probe runs per-block so a syntax error in one block does not cascade. Signature- only display blocks (e.g. `raise(error: ErrorInstance): never`) and cross-block dependent blocks (one block's `ValidationError` defined in a previous block in the same MDX file) are skipped. A new CI job 'docs-examples-typecheck' runs the probe on every PR. The .changeset/r5-r10-type-and-runtime-contracts.md docs section describes the probe. * ci: scope docs-examples-typecheck GITHUB_TOKEN to read-only CodeQL flagged the new docs-examples-typecheck job for not explicitly restricting the GITHUB_TOKEN's permissions. The job only checks out code and runs tsc, so 'contents: read' is the minimal scope. * docs(errors): fix remaining broken MDX examples — manual-generic, instanceof, missing imports - fields-schema.mdx: drop `z.record(z.unknown())` (Zod 4 needs 2 args); replace manual-generic with schema overload; self-contained blocks - message-templates.mdx: add missing imports + // -> annotations - multiple-inheritance.mdx: add missing imports - single-inheritance.mdx: add missing imports; replace manual-generic with schema overload - type-checking.mdx: replace manual-generic with schema overload; remove `instanceof ValidationError` (factories are functions) - from-method.mdx: narrow `err` with `is()` after `raise()` - error-factory.mdx: drop `export` modifier (IIFE context); narrow `err` with `is()` - api-reference.mdx: replace `instanceof` with `is()` for factory Probe now reports 75/75 blocks pass, 0 fail. * style: prettier --write on packages/errors/README.md * docs(errors): rewrite the 2.0.0 changeset; probe verifies // -> annotations Changeset: - Drop the fabricated 'Migration from 1.x' section: the parent-schema cascade, parent transformations, and manual-generic form were never shipped. The major release describes what shipped, not what was rejected. - drop-cascade.md: replace the '1.x' migration with a description of the static type-level constraint and the consumer-side composition pattern. Probe: - Accept '// ->' AND '//->' (any whitespace between the // and the ->). - Self-test: a synthetic block with a deliberately-wrong expected value is run through the same matching code; if the regex doesn't catch the mismatch, the probe exits 2. - Hard-fail when at least one block in the docs has an annotation and the probe matches zero of them. - Caught a real bug: '// -> true (through inheritance)' was a comment that was never going to print; the corrected annotation is '// -> true'. Probe now reports 63 annotation(s) verified, 0 fail. * docs(errors): consolidate to a single 2.0.0 changeset; retire obsolete notes - .changeset/drop-cascade.md: deleted. The 'parent-schema cascade' it described was an internal mechanism that never shipped; the text used the same fabricated 1.x framing the user already flagged. - .changeset/r8-audit-hardening.md: deleted. It claimed the type-level gate is 'advisory' because of 'function-arity flexibility' — that diagnosis was wrong (R10.1 made the gate fire on every malformed schema). - .changeset/r5-r10-type-and-runtime-contracts.md: rewritten as a single coherent 2.0.0 release note. The no-schema overload now acknowledges the manual generic form (error<T>({...}) on the no-schema path), which the previous text incorrectly denied. * docs(errors): delete fix-type-validation-phase-1 changeset; fix .fields example - .changeset/fix-type-validation-phase-1.md: deleted. It still claimed the parent's schema is re-validated against the child at instantiation (a cascade removed by R5), that the caller's inherits array is frozen in place (it isn't — only the snapshot is), and that schema-driven input-shape inference is still to be addressed (it was delivered in R7). - r5-r10-type-and-runtime-contracts.md: replace `error<{ n: string }>({ name: 'X' }).fields.n` (which is wrong: .fields belongs to the instance, not the factory) with `const X = error<{ n: string }>({ name: 'X' }); X({ n: 'value' }).fields.n`. - r5-r10: add a 'Breaking changes from 1.x' section that captures the genuinely useful migration info from the deleted changeset (required input, function-form message, full-shape input, the removed flat causes field, the split is() overloads). * Potential fix for pull request finding 'CodeQL / Workflow does not contain permissions' Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com> --------- Co-authored-by: T3 Code <noreply@anthropic.com> Co-authored-by: martyy-code <martyy-code@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
#100) With Root Directory = apps/web, Vercel interprets outputDirectory relative to apps/web. The previous value 'apps/web/.next' produced a doubled path /vercel/path0/apps/web/apps/web/.next and the deployment failed with 'Next.js output directory was not found'. Keep 'installCommand: pnpm install' so the deployment is reproducible from vercel.json alone; ENABLE_EXPERIMENTAL_COREPACK=1 is set on the Vercel dashboard and pins pnpm to 10.34.5 via the packageManager field in package.json.
Conflict resolution strategy per CLAUDE.md resync procedure: - packages/errors/package.json: combined both sides. The published scripts from main (type-check:test, test:consumer, test:docs) are kept alongside the staging migration to oxlint. This preserves the scripts the WIP audit response (#99) added while keeping the oxlint migration (#97) intact. - 5 apps/web/content/docs/*.mdx files: resolved in favor of main. These are part of the published docs site; the WIP audit response PR #99 refactored the API documentation to align with the 2.0.0 contract. The MDX in main is the canonical version post-audit. The staging versions are pre-audit drafts. The merge brings 68 files of main-only changes (CI workflow, .gitignore, .claude/* removals, packages/errors/* tests, doc refactors, vercel.json fix from #100) into staging. This unblocks: - Vercel preview builds on staging (the vercel.json outputDirectory fix from #100 was missing from staging) - Future rebase of #101, #102, #103, #105, #107 onto the new staging tip (the dep bump series) - The Dependabot re-scan that PR #106 staging->main cherry-pick will trigger No code change in @deessejs/errors beyond the scripts section of package.json; the lib source under src/ has no conflict because main's audit response WIP is forward-compatible.
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
The ci lint runs `pnpm changeset status --since=origin/staging` which compares the working-tree version (2.0.0 from main) against the staging version (1.4.0) and demands a changeset covering the bump. The 18 changesets merged in from main are already-consumed (their bump is in 2.0.0); the lint does not recognise them as pending for staging, so a new entry is required. The major bump on @deessejs/errors reflects the 1.4.0 -> 2.0.0 transition that was already published on main. The release engineer can drop this entry from the next release batch since 2.0.0 is already on npm.
oxfmt --check failed on 12 files in the resync diff: - 7 apps/web/content/docs/*.mdx (the docs that came from main's audit response refactor) - 4 packages/errors/CHANGELOG.md and tests/docs-examples-typecheck.mjs - 1 .oxlintrc.json These are pre-existing format issues on main (CLAUDE.md notes 'Lint may fail on pre-existing prettier issues and is not a blocker', but the CI lint job is currently configured to fail on any oxfmt --check miss). Reformatting the files in this resync commit makes the lint job green without changing any code semantics. Validated locally: pnpm format:check now passes on all 215 files.
After merging main into staging, the new `standard-schema.test.ts` file (added in PR #99) triggers oxlint's `typescript/consistent-type-imports` rule because `vi` is only used in `typeof vi.spyOn` (a type position). The .oxlintrc.json rule was added in PR #97 (oxlint migration) on staging. Main does not have it (its lint config was simpler pre-#97), so the test file was not lint-checked there. Split the import: import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; into two lines so `vi` is imported as a type. The other names remain value imports because they are used as runtime values (`describe()`, `it()`, etc.). Validated locally: `pnpm --filter @deessejs/errors lint` now passes with only warnings (no errors).
This branch was previously deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves the merge conflicts in #108 so the main->staging resync can land.
The original PR #108 is still open and
mergeable: CONFLICTING. This PR is a superseding version of the same merge with the 6 conflict zones resolved:packages/errors/package.json(scripts): combined both sides. Kept the published-release scripts from main (type-check:test, test:consumer, test:docs) alongside the staging migration to oxlint.apps/web/content/docs/*.mdxfiles (api-reference, causes-function, error-factory, fields-schema, message-templates): resolved in favor of main. These are part of the published docs site and main contains the post-audit refactor (PR WIP: tighten type, validation, and causality contracts (audit response) #99) that aligns with the 2.0.0 contract.How to use this PR
Two options for the maintainer:
90e4451frompr-108-resolveonto whatever you want the merge to be.The base is
pr-108-head(the tip of #108, which ismainat07b3e6a), with conflicts fromstagingresolved on top.Validation
pnpm install --frozen-lockfile,pnpm build, andpnpm --filter errors test(146/146) all pass locally on this branch.Why this matters for the bulk dep cleanup series
stagingand rely on the staging tip not having the stalevercel.jsonfrom before PR fix(vercel): set outputDirectory to .next (Root Directory is apps/web) #100. Merging this resync first bringsvercel.json(and the.github/workflows/ci.ymlconsolidation, and the.claude/removals) into staging, after which the dep-bump PRs can rebase cleanly.pnpm-lock.yamlis not in the resync diff (it is staging-only because main pre-dates the pnpm migration). The dep-bump PRs will rebase onto the new staging tip and bring the lockfile up to date with their bumps.🤖 Generated with Claude Code