Skip to content

Fix 2.0.1 release blockers: engine bugs, typings, packaging/CI and docs - #282

Draft
ffMathy wants to merge 105 commits into
masterfrom
ccr-f7030c4e-rhdc1v
Draft

ffMathy wants to merge 105 commits into
masterfrom
ccr-f7030c4e-rhdc1v

Conversation

@ffMathy

@ffMathy ffMathy commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Work in progress. This PR fixes the problems found in an audit of the unreleased 2.0.1 on master, before it is published. It covers the runtime engine, the typings, packaging/CI and the docs.

Merged so far

  • Groundwork
    • The 9 spec/**/*.test.ts regression files run again.
    • No inline type import modifier, so the typings parse on TypeScript < 4.5.
    • util instead of node:util.
    • Context symbols use Symbol.for(...).
  • Engine (src/internals/ rewritten around per-substitute state):
    • invalid received(n) counts throw
    • symbol assertions on members named returns/throws/… are assertions
    • assertions never run substitutions
    • every call through a stored or destructured method reference is recorded; .call/.apply/.bind work
    • nested auto-substitutes are cached and support nested setups/assertions, and root setups no longer leak into them
    • new sub[configure]() view to re-configure overlapping setups
    • precedence: most specific matcher first, then most recent
    • sub[mimick](instance) implemented
    • Arg.all() after leading arguments matches the rest
    • Arg.any('object') excludes null; Arg.is validates its predicate, and a throwing predicate counts as a non-match
    • failures throw synchronously whenever the outcome is known
    • colour only on a TTY or with FORCE_COLOR
    • safe with Error.stackTraceLimit = 0
    • linear performance
  • Typings:
    • .mimicks() on methods returning unions or booleans
    • symbol API available on generic SubstituteOf<T>
    • one consistent string/symbol conflict rule
    • optional members, index signatures, zero-argument overloads
    • [configure]() typed
    • SubstituteException exported
    • type-level tests (npm run test:types) and a TypeScript 3.6 minimum check
  • Packaging/CI:
    • exports map and ESM entry, so the default import works under native ESM
    • prepack build; specs compile to dist-spec/
    • engines verified on Node 10
    • CI on Node 22/24/26 plus a minimum-Node smoke test
    • compatibility checks (ava, jest, mocha, node:test, vitest) run against the packed package
    • publish workflow: latest/beta dist-tags, provenance, no broken GitHub Packages job
    • CONTRIBUTING.md

Still in progress

  • Small engine refinements: a usage error for root-level [returns], capped call listings, extra hints in messages, NODE_DISABLE_COLORS/TERM=dumb, a literal-setup index.
  • README rewrite with type-checked and executed snippets (npm run test:docs), MIGRATION.md (1.x → 2.x, beta → 2.0.1) and CHANGELOG.md (closes Update documentation #234).
  • A re-verification of every audit finding and a fresh bug hunt.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt

- run the spec/**/*.test.ts regression files again (lost in #280)
- drop inline 'type' import modifiers so the typings parse on TypeScript < 4.5
- import 'util' instead of 'node:util' (Node < 14.18 compatibility)
- use registered symbols (Symbol.for) so duplicate package copies interoperate
- add a 'configure' context symbol (runtime support follows)
- remove the unused src/api/Constants.ts

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Replace the node/recorder model with an explicit SubstituteState per
substitute (root or cached auto-substitute): append-only received-call
records indexed by member, configured substitutions kept apart from
them, an optional mimicked instance, and a cache of auto-substitutes
keyed by (kind, member, arguments). Thin proxies translate operations
onto it: real use, setup chains, assertion chains and a configure view.

Existing specs updated where a fix-spec decision changes behaviour:
- RecordedArguments.spec: argument matching is one-directional (D3)
- received.spec (#18): a bare add(Arg.all()) is a setup, not a call (D3)
- issues/178: received(3).subSection fails both ways, so it throws
  synchronously; an ambiguous case keeps the deferred report (D9)
- clearReceivedCalls.spec: asserts behaviour instead of the removed
  recorder internals
Recorder.spec and RecordsSet.spec are removed with the classes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Add one regression test per audit finding (named with its id) under
spec/regression/fixes/, plus tests for the decisions that add or
change behaviour (D2 auto-substitute caching, D5 configure, D9
deferral, D11 string assertion forms, D12 mimick, D13, D14, D16-D19)
and for two copies of the package interoperating (G:RG-8).

Engine changes found while testing:
- every proxy target carries the printer, because util.inspect
  inspects the target of a proxy instead of calling its traps
- only the call-site frame is captured per call, which halves the
  cost of a call (D19)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
After sub[mimick](instance), reading a member that the instance does
not have now returns undefined, as on the instance itself. The
substitute keeps an auto-substitute only where it needs one: the
string received/didNotReceive forms, members with configured calls,
and members configured through nested setups.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… spec output

- Add an "exports" map with a generated native ES module entry
  (dist/index.mjs + dist/index.d.mts, written by packaging/build-esm.js),
  so `import Substitute from '@fluffy-spoon/substitute'` is the Substitute
  class under native ESM and TypeScript node16/nodenext/bundler. CommonJS,
  "main"/"types", package.json and deep imports of dist/ files keep working.
- Build before packing (prepack), so npm pack / npm publish always ship a
  fresh dist/ (G:PK-3).
- Compile the specs into dist-spec/ (npm run build:spec), so npm test never
  leaves dist/ in an unpublishable state (G:PK-3).
- Sync package-lock.json to 2.0.1 (G:PK-4).
- engines.node stays >=10: the packed build was smoke-tested on Node
  10.0.0 to 26 (CommonJS) and 12.17.0+ (ESM); Node 8 lacks
  util.isDeepStrictEqual (G:PK-2).
- publishConfig pins the npm registry; packaging/dist-tag.js computes the
  npm dist-tag for a release; better keywords; volta pin moves to Node 24.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…:test check

- The pretest script (npm run install:local) packs the repository root like
  npm publish does and installs the tarball with --no-save; the runners
  import '@fluffy-spoon/substitute' instead of ../../../src (G:CI-2).
- Strip NODE_TEST_* from the environment of the nested runners. A nested
  `node --test` inherited NODE_TEST_CONTEXT and exited 0 although its test
  failed, so the node:test check failed on Node 20.11+ (G:CI-2).
- Accept the runners' reports for a synchronous failure as well as for an
  assertion thrown on process.nextTick, and match the exception name and
  message separately (ava and node:test print them apart).
- Update the runners (ava 6.4, jest 30, mocha 12, vitest 5, tsx, ts-jest,
  TypeScript 5.9) so the checks run on Node 22, 24 and 26; mocha 10 failed
  to start on Node 26. This also removes the critical/high audit findings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…rs; fix publishing

- Node CI: run on push and pull_request (and as a reusable workflow) on
  Node 22, 24 and 26 instead of 18/20/21, and run
  `npm run test:types --if-present`.
- New compatibility job: the compatibility checks against the packed
  package (G:CI-2).
- New minimum-node job: packs the package and smoke-tests it on
  MINIMUM_NODE_VERSION (10.0.0, = engines.node) and on 12.17.0 for the ES
  module entry (G:PK-2).
- Publish: trigger on `published` releases, run the full CI workflow
  first, check that the release tag matches package.json, publish stable
  versions as `latest` and prereleases as `beta`, with provenance.
- Remove the GitHub Packages job. GitHub Packages only accepts packages
  whose scope is the repository owner (@ffMathy), so it could never host
  @fluffy-spoon/substitute and failed every release (G:CI-1).
- CodeQL: action v4, drop the obsolete HEAD^2 checkout, explicit
  permissions. Dependabot also watches compatibility-checks/. The bug
  report template asks for the module system and the test runner.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
packaging/package.test.js runs with `npm test`. It packs the repository like
npm publish does (starting from a stale dist/), installs the tarball into a
fresh consumer project and checks:
- G:PK-3: the tarball has the entry points and no spec/stale output; the
  spec build goes to dist-spec/.
- DOCS:ESM: the default import works under native ESM and in TypeScript
  (node10, node16, nodenext, bundler); require, deep imports and
  package.json still work.
- G:PK-4: package-lock.json version = package.json version.
- G:PK-2: engines.node = the version the minimum-node CI job tests.
- G:CI-1 / CI:dist-tag: publishing only targets npm, tag logic.
- G:CI-2: nested node --test runs report failures; CI runs the
  compatibility checks against the packed build.
- CI:matrix: supported LTS lines and the type tests.

CONTRIBUTING.md (linked from the README, previously a 404) documents
install, build, test, test:types, the compatibility checks, CI and the
release process.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
- One rule for the setup methods (T:TY-2, G:RG-4): `.returns` / `.throws` /
  `.mimicks` / `.resolves` / `.rejects` are offered unless the value they are
  accessed on (property type or return type) has a member with that name; the
  symbol forms are always offered. Checks are non-distributive for the method
  types, so union return types keep a single `mimicks` (T:TY-1).
- D11: `sub.received` / `sub.didNotReceive` are only offered when T has no
  public or private member named received, didNotReceive, returns, throws,
  resolves, rejects or mimicks; the symbol forms are always available,
  including on SubstituteOf<T> for a generic T (T:TY-3, G:RG-3, T:TY-14).
- D12: `mimick` is symbol-only (`sub[mimick](instance)`) (T:TY-5).
- D5: `sub[configure]()` returns a view whose members only expose the setup API.
- Overloads: up to 8 overloads in one bivariant inference step (T:TY-11),
  zero-parameter overloads anywhere (T:TY-10), `(...args: unknown[])`
  (T:TY-13), positional signatures before the Arg.all() ones.
- Optional members (T:TY-7), index signatures next to named members (T:TY-8),
  members returning `never` (T:TY-12), `then` typed `never` and `toJSON`
  without setup API (T:TY-16, D20).
- Export SubstituteException from the index through a public interface, so the
  typings do not reach the internals or @types/node (G:RG-9).
- overlap.spec.ts: use the string received/didNotReceive forms through `any`,
  since D11 no longer offers them in the typings for these types.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
- spec-types/: fixtures type-checked by `npm run test:types` (strict, and
  spec-types/loose without strict), one file per finding; must-fail lines use
  `@ts-expect-error`. `npm test` runs them first.
- spec-types/min-ts: `npm run test:types:min-ts` builds dist/ and type-checks
  a consumer of the built typings (resolved through package.json, without
  @types/node) with an old TypeScript installed by npx (default 3.6, the
  measured minimum; other versions as arguments).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
With the D9 engine change, the old scenario fails synchronously. Three
calls followed by a property-style received(2) can only be reported on
process.nextTick, so the runners are still checked for that path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Editors then show the documentation of received, didNotReceive,
configure, mimick and the setup methods on hover.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
sub[returns](1) (and [throws], [resolves], [rejects], [mimicks]) on a root
substitute, or on its configure() view, used to read a member keyed by the
symbol and return an auto-substitute, so nothing was configured. It now
throws a SubstituteException usage error that points to member/call setups
and to sub[configure]() for a substitute returned by a configured call.
The string names stay ordinary members (D11).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
A failing assertion on a member with hundreds of received calls produced a
message with one or two lines per call. The listing now stops after 50
entries with "› … and N more", using the listing's own marker. The counts in
the expectation line still cover every call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
The colour decision now follows Node's own policy more closely:
FORCE_COLOR still wins ('0'/'false' off, anything else on); otherwise a
non-empty NO_COLOR or NODE_DISABLE_COLORS, or TERM=dumb, turn colours off;
otherwise stdout must be a TTY. The decision is a pure function,
shouldUseColors(env, stdoutIsTTY), so it is tested without a real TTY.

The existing A:RT-14 test now also clears NODE_DISABLE_COLORS and TERM, so
its TTY case does not depend on the environment the tests run in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Two hints, after the listing of received calls:

- When a method assertion finds too few calls and the member was also read
  without being invoked: "@Substitute.m was read N time(s) without being
  called; reading a method does not count as calling it." The same hint is
  given when a member that was read and invoked fails a property-style check
  with a count above its calls.
- When didNotReceive().m(...) fails on a member that was only read, for
  example passed as a callback (the A:RT-3 residual forced by D9): the hint
  explains that the assertion is decided when the member is read and that
  sub[clearReceivedCalls]() after the arrange step resets the reads.

SubstituteException's mismatch description gains optional `explanation`
(continues the expectation line) and `hints` (lines after the listing).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… method

Amended D9: a property-style assertion such as `sub.received(2).m` on a
member that has only ever been invoked is reported on process.nextTick when
it is not invoked. Its message said "Expected to receive 2 property reads
matching m, but received none." and nothing else. It now continues with
"m was never read as a property; it was called 1 time as a method. To assert
calls, invoke it: sub.received(2).m(...)", with the path of nested
substitutes (sub.logger.received(2).info(...)).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…utated arguments

Resolving a call compared it against every literal substitution of the
member, and configuring one compared it against all earlier ones, so 8000
literal setups plus 8000 calls took about 4.6 s. All-literal substitutions
are now indexed per member by a stable fingerprint of their arguments:
primitives by value, functions, substitutes and symbols by identity, and an
object only as "an object", so the key never goes stale when an argument
object is mutated after the setup (literal arguments are compared as they
are when the call is made, D15). The deep-equal confirmation and the D4
precedence (most specific class, then most recent) are unchanged. The same
workload now takes about 0.17 s. Literal setups with object arguments still
compare against the setups with the same primitives in the same places.

The auto-substitute cache looked entries up by a structural fingerprint
only, which goes stale when an argument object is mutated: after
api.get(request).body.returns('ok') and request.headers = {...},
api.get(request).body was a new auto-substitute (D2). Entries are now also
found by the identity of the argument objects.

The ratio test 'the cost of a call does not grow' now takes the best of
three runs and compares 2000 with 32000 calls against a bound of 48x
(linear is about 16x, quadratic about 256x), so CPU load does not fail it.
New: 8000 literal setups plus 8000 matching calls in under 1 s (best of
three, directly and through configure()) and a growth check for them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Every example now compiles under strict TypeScript and does what the text
says (the old snippets mostly failed to compile or crashed at runtime).

- Fix the malformed badge HTML and the requirements: Node.js 10 for
  CommonJS, 12.17 for the ES module entry point, TypeScript 3.6.
- Document importing (CommonJS, ES module default and named imports),
  sequences that repeat their last value, promises on properties,
  mimicks, the Arg.any type strings, Arg.all() for the rest of the
  arguments, the .not matchers, match order and precedence, configure(),
  partial mocks with [mimick](), auto-substitutes and nested members,
  received(count) validation, property checks, what counts as a call,
  clearReceivedCalls, SubstituteException, the assertions reported on
  process.nextTick, the name-conflict rules for TypeScript and
  JavaScript, the symbol API, special members, typing limitations and
  test runners.
- Replace the Substitute.disableFor section, which described an API that
  no longer exists.
- Link the migration guide, the changelog and CONTRIBUTING.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Covers npm latest moving from 1.208.0 to 2.x, the Node.js and TypeScript
minimums, the removed APIs (Substitute.disableFor, clearSubstitute and
ClearType, the string mimick(instance)) with their replacements, the
symbol API and the name-conflict rules, and the behaviour changes:
sequences repeating their last value, cached auto-substitutes and nested
checks that really check, matcher calls being setups, match order,
configure(), what counts as a call, checks never running setups,
received(count) validation, matchers and messages. Also the ES module
default import, the exports map and the moved deep import paths. Each
section says which old versions it applies to; the "after" examples are
checked like the README's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Keep a Changelog format. The 2.0.1 entry summarises the fixes, changes,
additions and removals since 2.0.0-beta.4 in user terms; the beta entries
are reconstructed from the git history.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
`npm run test:docs` builds the package, then spec-docs/check.js extracts
every typescript and js code block from README.md, MIGRATION.md and
CHANGELOG.md, type-checks the TypeScript ones under strict against the
built package (resolved through package.json and its exports map, like an
installed copy) and runs each block in its own Node.js process.

Examples state what they do in comments that the check enforces:
`// prints <output>` must print exactly that, and `// throws <Name>`
must throw. Any other output, exception, uncaught exception or unhandled
rejection fails the check. HTML comment directives share setup code
between blocks (name=/uses=), mark ES modules, compile-only and skipped
blocks, an expected uncaught exception, and an error message text that
must match. Relative links and #anchors are checked too.

spec-docs/self-test.js runs the check on fixtures/broken.md, whose blocks
and links are broken on purpose, and fails unless each problem is
reported. The whole run takes about 10 seconds. CI runs it in the test
job.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…tion (D10, D11)

A call of the string `received` / `didNotReceive` with an Arg matcher among
its arguments was always taken as a setup (D3) of a member with that name,
so `sub.received(Arg.any()).add(1)` silently configured something and the
"assertion" passed, and `sub.didNotReceive(Arg.any()).value = 1` threw
"Property assignments cannot be configured". By D11 such a call followed by
a member access or an assignment is the assertion API: received() now
reports the invalid count (D10) and didNotReceive() asserts, ignoring its
arguments as it does without matchers. Followed by a substitution method,
and inside a configure() view, it is still a setup of the user's member.

Found by porting engine A's D11 test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…tion

A failed `sub.received(1).isEnabled = false` listed the assignments under
"All property or method calls to @Substitute.isEnabled received so far:".
The listing of an assignment assertion only contains assignments, so it is
now headed "All property assignments to ... received so far:". The other
headings are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… setups

Code under test that reads a member called returns (or throws, resolves,
rejects, mimicks) on an unconfigured call result gets the setup method,
so calling it reconfigures the substitute. Configuring the value first
avoids that.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…e (R3-ADV-5, E6)

The jest check accepted "type: 'CallCountMismatch'", which is part of
Node.js's fatal-exception dump, so it passed when jest crashed. The jest
fixture now has a passing test before and after the failing one, and the
check requires jest's report: the failure of that test with "Tests: 1
failed, 2 passed, 3 total". jest 30 on Node.js 22 cannot attribute an
exception thrown from a microtask to the running test (Node.js 22 loses the
AsyncLocalStorage store there), so on Node.js 22 the check also accepts
jest's "Test suite failed to run" for the file, with "Tests: 3 passed, 3
total". Every runner's output must be free of a Node.js crash, and jest's
and vitest's "called at" lines must name the TypeScript source lines (E4).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
The feature check for AggregateError read globalThis, which Node.js 10
does not have, so requiring the package threw a ReferenceError there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…ith keyof T

`T[P & keyof T]` intersects each key with the whole key union of `T`, which
distributes over hundreds of keys for lib.dom types every time a member type
is computed (TypeScript computes every member of a substitute on the first
member access). `T[Extract<P, keyof T>]` is a single lookup, and in generic
code it still resolves to the constraint's member type on assignment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Hashing a string longer than 4096 characters computed every sampled
position through sampledPosition, which made 10k calls with 5000-character
strings slower than hashing them in full before. The prefix, the strided
samples and the suffix now have loops of their own (the same positions).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…T33/T34

Both are pre-existing (they fail the same way at 6cb1c22) and are recorded
with the way around them, which is checked on TypeScript 3.9 to 5.9:

- assigning a plain function to a callable member in the assertion view
  (`button.received().onClick = handler`): the member's type there also has
  the `Arg.all()` call signatures. Use
  `(button.received() as Button).onClick = handler`.
- in generic code, checking a set of a property typed as the type parameter
  itself (`current: T`): use `(holder.received() as Holder<T>).current = value`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…of reading members from T

Members<T> now picks `T` itself in generic code: it is an indexed access whose
key is `any` for the plain object type (`Pick<T, keyof T>`, reached through a
string index signature), and TypeScript leaves out an `any` branch when it
cannot decide `MembersKind<T>` for a type parameter. Indexing the mapped
object type gives `T['total']` there, which accepts the constraint's member
type, so the per-member `T[Extract<P, keyof T>]` lookup is no longer needed.

Concrete types are mapped as before (a type with a string index signature
directly, anything else through `Pick<T, keyof T>`, a union as one object).
Instantiations for `Substitute.for<Document>()` plus 5 setups/checks:
115,056 -> 112,006 (6cb1c22: 107,819).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…equire() (P2)

CommonJS code that require()s the package, bundled with @rollup/plugin-commonjs on
default options while the package stays external (also Vite 7 and older SSR builds),
gets the Substitute class instead of the exports object: the plugin turns require()
into a default import, which Node.js resolves to the ES module entry.

P29 keeps that behaviour and documents it with its workarounds. test/bundlers.ts now
bundles bundlers/require-entry.mjs, which imports CommonJS code that require()s the
package, and checks that each documented setting gives the exports object:
commonjs({ esmExternals: true }), commonjs({ esmExternals: [the package] }), bundling
the package with Rollup, Vite's ssr.noExternal, and Vite 8's default externals. It also
checks that each bundle really keeps the package external or really bundles it, and
that the caveat itself still holds, so the docs are revisited when the tools change.

A packaging test (P2) makes sure the compatibility checks keep covering each setting,
and CONTRIBUTING describes the new check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…ery smoke-tested Node.js (R3TD-5)

CONTRIBUTING and the header of packaging/smoke/deep-imports.js said that deep imports
fail on 12.17 to 12.22, all of 13.x, 14.0 to 14.18 and 16.0 to 16.8. Measured with the
packed package, they fail only on 12.17 to 12.19, 13.x and 14.0 to 14.12; on 12.20 to
12.22, 14.13 to 14.18 and 16.0 to 16.8 the form without .js works, as MIGRATION says.

packaging/smoke/deep-import-support.js now holds that table (15.x, which nobody
checked, is left out), and deep-imports.js checks it on the Node.js version it runs on:
the forms that should work must work, the others must fail with Node.js's error. The
minimum-node CI job runs it on all four old versions it installs, not only on 10.0.0.
It passes on all 26 versions from 10.0.0 to 26.13.1. deep-imports.mjs says that its
forms with an extension need 14.19+ or 16.9+.

The R3TD-5 packaging test pins the table to the measured results and checks that
CONTRIBUTING, MIGRATION and both smoke files state the same ranges.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
A method reference invoked later is a call made where it is invoked
(E1), the adjacency fallback applies only when neither operation has a
frame, and promise-job async frames are ignored (E2), a structural
argument hash with bounded cost per argument, also for cycles, native
errors, long strings and wide values (E3), "called at" text formatted
by V8/Node.js with source maps, structured frames read from a separate
capture (E4), Error.prepareStackTrace never changed for the process
(E5), deferred reports thrown from the queueMicrotask captured at load
(E6), and the runtime's own util.promisify.custom and util.inspect.custom
(E7).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Setups and checks through a type parameter's constraint (T33), the
optional-callback limitation of the assertion view pinned with its
workarounds (T34), inverse documentation at Arg.is.not / Arg.any.not
call sites (T35), unions whose variants declare null-only members no
longer reduce to never (T36), substitutes of function types and
callable interfaces configured and checked through their calls (T37),
and Arg.any('undefined') only fits parameters that accept undefined
(T38).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Compatibility checks that bundle CommonJS code which require()s the
package with each documented setting, and pin the default
@rollup/plugin-commonjs caveat (P29), and a version-aware deep-import
smoke test whose table CONTRIBUTING, MIGRATION and the smoke files
must agree with, run on every Node.js version the minimum-node job
installs (P30).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…fixes

- Which calls lead to a setup or a check: calls through a method reference
  handed to the code under test, and calls from promise jobs, are kept (E1, E2);
  position alone decides only when neither side has a stack frame; the library
  restores Error.prepareStackTrace exactly (E5). Checked examples for both.
- "called at" lines keep source maps and custom formatters (E4).
- Assertions that fail later: reported from a microtask; how jest 29/30, vitest,
  ava, mocha, node:test and plain Node.js report it; fake timers (E6, R3-ADV-5).
- Performance: the bounded argument hash, its limits, and the shapes that can
  still share a hash (E3); the bounded nested-matcher search (D27 limits).
- Special members: the runtime's own util.promisify.custom (E7).
- Importing / Imports and packaging: the Rollup commonjs external require()
  caveat and its workarounds (P2).
- TypeScript: function-type substitutes (T37), constrained generics (T33),
  unions with null-only members (T36), Arg.any('undefined') (T38), and the
  remaining limitations with checked workarounds (optional callbacks in checks,
  callable members in checks, Arg.any.not(type), T | undefined substitutes,
  TS 3.6-3.8 nullable members in generic code). Removes the stale
  @ts-expect-error that made test:docs fail.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…er operation (E8, E11)

R4-ADV-1 (E8): a read that is invoked later always takes the call site of the
invocation, so the frame of the call it becomes is where it was invoked, also
when the code under test invokes a method reference on the substitute again
(Reflect.apply(fetch, api, [id]), an uncurried Function.prototype.call, a
wrapper). The `this === proxy` shortcut is gone; a setup of the value the code
under test got back no longer erases its call.

E11: the structured first frame is read from the record's own capture with a
prepareStackTrace that throws, which V8 does not cache, so the capture still
formats its text normally later. There is no second capture per operation, and
the traps capture the call site themselves, only for operations that are
recorded (each frame between the capture and the trap costs). Operations that
record nothing read a throwaway capture.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
R4-ADV-4: Node.js compares an object as an error (name, message, cause, errors)
when isNativeError(value) || value instanceof Error, unless its toString tag is
[object Object]. The hash now uses the same predicate (whether error-like objects
count is found out once at load), so an Error.prototype object with the tag
'Error' hashes like the native error it is deep strictly equal to, and objects
tagged [object Object] hash by their keys, which also covers Node.js 24's
asymmetric comparison of such native errors.

The E3 property test generates error-like objects and native errors tagged
[object Object] as well, and prints the values when a pair disagrees.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…ups again (T39, R4TD-1)

A member whose type is a union of function types with different return types
(`Cat | Dog` methods, `this`-returning methods in unions, union-typed callbacks)
is expanded per variant since round 4, so a call returned a union of setup APIs
and `.returns()` / `.resolves()` / `.mimicks()` / the configure view took `never`.

Each variant keeps its own signatures, but when the variants' overloads at the
same position return different types, every variant's call result is now
computed from the union of those return types. The choice is made lazily inside
the call's return type, so type-checking cost is unchanged (DOM probes and the
union of all lib.dom elements check as fast as at ec64181), and in generic code
it falls back to the constraint's own overload (T33 unchanged).

Generic code whose constraint is such a union is pinned in limitations.ts with
its workaround (cast to SubstituteOf<Constraint>).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… (E9)

R4-ADV-2:
- the search for nested matchers visits each container once per argument
  (a visited set next to the budget), looks at 4,096 items and keys per
  argument at most, and remembers (weakly) the objects it found too wide to
  search, so a lookup table passed again and again is listed once;
- within one hash, the shallow part of a wide object, Map or Set is computed
  once however many values refer to it, and objects with more than 4,096 keys
  (Maps and Sets with more entries) are hashed by their size only;
- a call computes the structural hash only when a literal substitution could
  match it: the same objects as a literal substitution answer by identity
  when no literal substitution is more recent, and a call whose primitive
  arguments are those of no literal substitution skips the index.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
R4-ADV-3: the mocha, ava, vitest and node:test fixtures get passing tests
before and after the failing one (mocha and ava a second file as well), and
the checks assert what really happens:
- mocha reports the test as passed, then as failed ("Uncaught"), and aborts
  the run: later tests, in the file and in later files, do not run;
- ava reports the test as passed, "Uncaught exception in <file>" and "<file>
  exited with a non-zero exit code"; the unfinished tests of that file are not
  reported; other files are;
- vitest and node:test run and report every test, and fail the run with the
  error (vitest names the last test that ran).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…objects is searched" (E9)

An argument looks at 32,768 items and keys in all at most (not 4,096), so that
an array of 1,000 objects with a few keys each is still searched completely,
as the README says.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…peScript version (T40, R4TD-2, R4V-1)

The direct setups compile with TypeScript 4.8 and newer. With older versions the
typings cannot avoid two limitations, now pinned and documented in the fixture
header from cross-version harness runs (3.6 to 5.9 and 7.0):
- 3.6 to 4.7: calls of optional methods and of `fn | undefined` members are not
  callable with a constrained type parameter (`sub.reset().returns()`);
- 3.6 to 3.8: properties whose type includes null/undefined have no setup API,
  with a constrained type parameter and in an interface instantiated with any
  type parameter (`maybe?: T`, `orNull: T | null`).
The configure view and the checks work on every version; the min-ts consumer
now checks those workarounds with TypeScript 3.6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…neric code (T41, R4TD-3)

With `T extends { [key: string]: number; port: number }`, `sub.timeout.returns(5)`
and `sub[configure]().timeout.returns(5)` took no value: the setup API was computed
from `T[string]`, and TypeScript never lets a value be written to `T[string]` of a
type parameter. For keys that exist only through a string index signature, the
member is now computed by a conditional type over the members type, which
TypeScript resolves with the constraint when the member is used, so the setups
take the index signature's type (also for union-typed index signatures). Concrete
types are unchanged.

Checking a set of such a key (`sub.received().timeout = 5`) still does not compile
on any TypeScript version (TS2339: a write through an index signature of a generic
type); the fixture pins it with the workaround `(sub.received() as Settings).timeout = 5`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… exports (PK4-2)

With vitest's server.deps.inline and deps.interopDefault: false, the default import of
dist/index.js is an object with only some of the exports, and the namespace holds every
named export plus that object as its default. The wrapper required default === Substitute
and threw "could not read the exports" although the namespace was complete.

The generated dist/index.mjs now accepts a view when every named export has the type it has
at build time, ignoring the view's default, and exports the named export Substitute (the
default export found at build time) as its default. The packaging test simulates the new
shape and a namespace with undefined values; the compatibility checks run the inlined vitest
exports test with deps.interopDefault: false too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…agerly (GenericKind comment)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…/ (PK4-4)

packaging/package.test.js deleted dist/, wrote a stale dist/spec/Stale.spec.js and packed
the working tree, so an interrupted npm test left no dist/ at all, although CONTRIBUTING
says npm test never writes into dist/.

The checks now copy the working tree (uncommitted changes included; without dist/,
dist-spec/, .git, other dot-directories and node_modules/, which is linked instead) to a
temporary directory, put the stale dist/ there and pack that copy. A new test compares a
snapshot of the working tree's dist/ before and after packing. CONTRIBUTING describes the
temporary copy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…d import (PK4-1)

ES module code bundled into CommonJS output while the package stays external (Rollup format
'cjs', esbuild format 'cjs' with packages external, webpack with a commonjs external, a Vite
SSR build with CommonJS output) require()s the package at run time, and its default import
is module.exports, the exports object, not the Substitute class.

compatibility-checks/test/bundlers.ts now bundles bundlers/named-entry.mjs (named import
only) with each of them and checks that it works, checks Rollup's output.interop: 'auto'
workaround for the default import, and checks that the caveat itself still holds, so the
README and MIGRATION wording is updated when the tools change. A packaging test makes sure
these checks stay in place. CONTRIBUTING describes them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…on return types (T39)

The T39 call results took the position of the overload in the 8-slot expansion
as a type argument. Identical overloads in several positions then gave distinct
signature types, so their intersection no longer collapsed. For a rest parameter
typed as a union of tuples (`log(...args: [string] | [string, number])`) every
position is a union, and the combinations multiplied: type-checking such a
substitute took minutes, and TypeScript 5.4 ran out of memory.

The union of the variants' return types is now keyed by the overload's
parameter list (as TypeScript matches signatures of a union of function types),
so identical positions give identical types again. The T39 fixture now
includes such a member, so a regression makes `npm run test:types` hang.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
E8 (R4-ADV-1): a method reference invoked by the code under test is a call
made where it is invoked, decided by frames, not by this === proxy.
E9 (R4-ADV-2): bounded cost per call for wide and shared arguments.
E10 (R4-ADV-4): error-like objects hash as Node.js compares them.
E11: one call-site capture per recorded operation; hot path back to
round-3 speed.
E12 (R4-ADV-3): compatibility checks pin each runner's behaviour around
a deferred report.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
T39 (R4TD-1): members typed as a union of function types get the setup
API again, with the union of the variants' return types.
T40 (R4TD-2, R4V-1): optional and nullable members in generic code are
pinned per TypeScript version, with the configure-view workaround.
T41 (R4TD-3): keys that exist only through a constraint's string index
signature can be configured in generic code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
P31 (PK4-2): the ES module entry decides completeness by the named
exports, so vitest with deps.interopDefault: false works.
P32 (PK4-4): the packaging checks pack a temporary copy of the
repository and never write into the working tree's dist/.
P33 (PK4-1): a compatibility case for CommonJS output with the package
external and the named import.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…fixes

- Importing (PK4-1, PK4-3, PK4-2, P33): prefer the named import; document
  CommonJS output with the package external (Rollup/Vite 5-7 cjs for any
  source; esbuild, webpack, Rolldown, Vite 8 for .mjs/type:module sources;
  Rollup output.interop: 'auto') and ts-node's ESM loader; qualify "Bundlers
  give the same exports"; vitest deps.interopDefault: false is checked.
- Which calls lead to a setup (E8): method references invoked with the
  substitute as `this` (Reflect.apply, fn.call, wrappers) are kept; builtins
  (Reflect.apply/call/apply/bind have no frame, Array.map does). Checked
  example. Stack-chain rule without the wrong version (R4TD-4).
- How arguments are compared (E10): error-like objects with the Error tag,
  [object Object]-tagged errors, Node 24+ order dependence. Checked example.
- Matchers inside objects (E9): shared containers searched once, 32,768
  items and keys per argument, objects once wider than 1,024 keys remembered.
- Assertions that fail later / Test runners (R4-ADV-3, E12): exact mocha
  (stops the run) and ava (ends the file's worker) behaviour, plus jest,
  vitest and node:test; drop "without crashing".
- Typing limitations, "In TypeScript" and MIGRATION "TypeScript" (R4V-1,
  R4TD-2, R4TD-3, T39-T41): TS < 4.8 optional/nullable members in generic
  code, union constraints, index-signature set checks, rest parameters typed
  as tuple unions; T41 index-signature setups; T39 union return types.
  Checked examples.
- Performance (E9, E11): re-measured on Node 22 against the build; 4,096
  cap, identity-first lookup, remaining slow shapes (unreadable arguments,
  matcher setups inside objects about 9 s, which 6cb1c22 and ec64181 share).
- CHANGELOG: T39 fix relative to 2.0.0-beta.4, T41, E8, E9, E12, PK4-2,
  CommonJS-output and ts-node note.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Update documentation

2 participants