Repository navigation
Conversation
- 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
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
T42 (R5TD-1): a concrete union whose variants declare a same-named method with different parameter lists (an extra optional parameter, other parameter types or required-argument counts, overloads, a generic method in one variant) has the full setup API on calls of that method again. Setups accept the return types of the variants whose overloads the call can reach. The residual limits are pinned in spec-types/limitations.ts and in the TypeScript 3.6 consumer. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…fixes - Performance (R5V-1, R5TD-2, E13, E14): wide objects, Maps and Sets hash every key and value (records with a budget of 4 objects), a sample of the values above 65,536 entries, families of 1,025 keys for objects with the keys of an earlier one, and a hash remembered across calls. Every number re-measured on Node.js 22 against the build (best of 3): hot path, shared and distinct wide shapes, records, the 200 literal setups with copies (0.2 s of 0.25 s is isDeepStrictEqual), colliding strings and symbols, unreadable values (about 50 to 70 ms for 4,000), matcher setups (0.8 s / 7.5 s) and memory (1,350 bytes per chain call). - How arguments are compared (E13, E14): unreadable values are equal only to themselves; a wide container keeps the hash of its first use, so a copy does not match a setup made after it changed, and a matcher put into it later is not recognised. Checked examples. - Matchers inside objects (E13): containers with more than 256 items or keys without a matcher are searched only the first time. - Error.stackTraceLimit (R5V-3, E15): read-only, accessor, missing and frozen limits work and are left as they were; accessors give no "called at" lines. Checked example with Object.freeze(Error). - "called at" text (E16): the formatter in place when the message is made, or the last one seen for reads in a chain. - Debuggers (R5-ADV-2, E16): no stops when Error.prepareStackTrace is a function (Node.js 20.20+, source-map-support, jest 29, vitest forks and threads); 40 stops for a 6-line test otherwise (Node.js 18, deleted formatter, vm contexts: jest 30, vitest vm pools), with the skipFiles hint. - Typing limitations, MIGRATION "TypeScript" and CHANGELOG (R5TD-1, T42): methods whose parameter lists differ between union variants have the setup API; exact rule, the two pinned limitations with casts, and unnamed parameters in editor hints. Checked example. - CHANGELOG: entries framed against 2.0.0-beta.4 (union methods with differing parameter lists, debugger stops as a change, tables passed with every call, stackTraceLimit shapes). - CONTRIBUTING: what a test run leaves in the temporary directory. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…() values (E27, E28) R6FE-6: an unconfigured read of __esModule is undefined and not recorded, so a substitute used as a whole module is its own default export under the interop helpers. [configure]() and [mimick] can still configure it. R6FE-5: Arg.any(type) and Arg.any.not(type) throw a TypeError for a type name outside 'any', 'string', 'number', 'boolean', 'symbol', 'undefined', 'object', 'function', 'array' and 'bigint'. mimicks() without functions throws a TypeError at the setup that names the member or call. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…E22) hashArguments, coarseHashArguments and identityHashArguments leave trailing undefined arguments out, so f(1) and f(1, undefined), which compare as equal argument lists from now on, land in the same buckets of the literal-setup index and the auto-substitute cache. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
R6FE-2: when a call is compared with a setup or a check, a position one side
does not have reads as undefined. It matches only a literal undefined or a
matcher that accepts undefined (Arg.any(), Arg.any('undefined'), ...), so
f(1) and f(1, undefined) match each other and set('a', 1, Arg.any()) matches
set('a', 1), while f(1) and f(1, 2) stay different. Re-configuring f(1) as
f(1, undefined) replaces the setup. Arg.all() is unchanged.
Existing tests updated where this deliberately changes the outcome: an
omitted argument now matches Arg.any() (decisions D3/D4, amendments D4/D15,
ported-from-a D14), f() is f(undefined) (amendments D15), and multiply(1)
after multiply(1, Arg.any()) is re-configured through the configure view
(returns.spec).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…ing or not a number, as V8 does (R6-ADV-6, E21) A missing, non-number or below-1 limit gives no frames for any error in V8. The library used to define the limit as 1 and delete it again around every capture, which changed Error's shape on every operation (1.4-1.9x slower hot path). Now such an operation shares one capture without a stack: no "called at" line, and D25 falls back to adjacency, as with Error.stackTraceLimit = 0. The property is never touched then. The round-6 E15 test expected frames with a deleted limit; E21 changes that. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
R6FE-3: the construct trap records `new sub(...)` and `new ns.Client(...)` as a call (shown as `new Client(args)` / `new @substitute(args)` in messages and String()), so setups and checks written with call syntax apply to it. It answers with the configured value when that is an object or a function, and with the cached auto-substitute of the call otherwise. A mimicked class, or a class or ordinary function given to mimicks(), is constructed; an arrow function is called. new on a bound substitute and on the deferred-read, configure and assertion views behaves like invoking them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
R6FE-1: String()/util.inspect of an auto-substitute print its path
(@Substitute.logger, @Substitute.getUser(1)) and, when it has any, its
received calls and setups, like a substitute; no dangling ': '. A substitute
also shows the calls and setups of its auto-substitutes under their paths
relative to it (logger.info('started'), logger.level => returns(3)), calls
in the order they were made. Inside another printout (an argument in a
failure message, a path) an auto-substitute shows only its path.
Existing tests that compared a root's printout to '@substitute {\n}' or to
the old 'property<name>: ' label are updated to the new output.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…tes (E25, E26) R6FE-4: Object.freeze, Object.seal, Object.preventExtensions and Object.defineProperty no longer make later reads crash with a Proxy-invariant TypeError. The proxy hides the own length/name of its bound-function target (ownKeys and getOwnPropertyDescriptor report no own properties), and the first structural change removes them, so the target's own properties are only the ones the code under test defined. A defined property is a real property that reads and assignments use and that is not recorded; a frozen substitute keeps answering setups and recording calls. The views the library hands out (assertions, configure views, bound functions, members configured both as a property and as a method) refuse these operations with a SubstituteException that names the operation. R6FE-8: a has trap makes `key in sub` and Reflect.has true for keys with a setup (property, method or nested setup) and for keys the mimicked instance has, and false otherwise, including protocol keys and the library's own members unless configured. Nothing is recorded. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…tes in jest and vitest (E24-E27) The jest-matchers suite checks that a substitute in a failure message shows its path ([Function @Substitute.logger.name] from pretty-format), that a frozen substitute still compares by identity, and that the has trap leaves toHaveProperty, toHaveBeenCalledWith, isMockFunction and clearAllMocks as they were. A new passing vitest-matchers suite checks the same with vitest's expect, util.inspect of an auto-substitute, and the __esModule probe. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… family anchors cost small records nothing (R6-ADV-4, R6V-1, R6-ADV-1, R6V-2, R6-ADV-5, R6V-3, R6-ADV-3; E18-E20) E18: every hash belongs to an operation (newOperation). The memo of a wide container written by an earlier operation may be stale; a hash that used one says so (lastHashUsedMemo). Literal setups are filed under fresh hashes, and a call whose memo-based hash finds no setup looks again with its fresh hash when the coarse hash allows a candidate. The auto-substitute cache does the same, and files the one entry per coarse hash that was filed under a memo-based hash without such a look under its fresh hash before it looks again. An unreadable value's identity verdict lives for its operation only, so a value that became readable matches an equal setup again. hashSettings.memos (internal) turns all memos off, for the property test that compares random scenarios with and without them. E19: families stay (100 calls with distinct 70,000-key objects need them), but a family is probed by the key with the lowest key hash and the one with the highest, not by its first key, and an object's family is no longer cached, so small records that share a field name with a wide object pay nothing. E20: a wide object found inside an entry, or being hashed, is marked in its memo for the operation, so shared wide objects and back-references are listed once per operation. The matcher search counts a cut only for a plain container, and runs its unbounded re-scan only for a container seen a second time. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…ash has a candidate (E18) The coarse hash alone sends every call with a shared wide table plus another object argument (render(props, theme), save(entity, config)) through a fresh hash, which lists the table every time: 10,000 such calls took about as long as at 45facfb (13 s) again. The narrow hash is the structural hash with every argument that holds a wide container counted as one tag. It is exact without memos, provided every container whose memo the hash used is still wide, which is checked without listing keys (Maps and Sets by size, objects by 257 of the keys they had). Literal setups and auto-substitute entries are grouped by it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…p only entries that met a wide container (E18, E19) E19: array items and the values inside an entry of a wide container are mostly records, which a wide object rarely is: they are not probed against the families before their keys are listed (by the hash or by the matcher search). A wide one among them is still found to be wide, or in its family, once listed, with the same hash. With 16 families, batches of small records cost 0.9-1.05x of the same library copy without families (74b8588: 3.2x). E18: the auto-substitute cache groups by narrow hash only the entries whose hash met a wide container, as only those can be equal to a call whose hash used memos; ordinary object arguments pay nothing for it. A call whose fresh hash is known already (a shrunk container, or the setup lookup computed it) looks with it. The E19 test now loads the library twice in each child process and measures the two copies by turns, in both load orders. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…6V-4, T43) A member type such as Record<K, () => number>[K] in generic code chose its signatures through a chain of two indexed accesses on the same object type. When TypeScript resolves such a member through its constraint, the chain is deep enough that it stops computing the inner access (it shares the outer one's recursion identity), and the member lost its substitute signatures on TypeScript 4.7 and newer. The box is now unwrapped with a conditional type. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…shape-only memo uses (E18, E19, E20) - A memo of an earlier operation that the hash only takes as "this container is wide" (inside an entry) is exact as long as the container is still wide (checked once per operation without listing): sessions sharing a config object or tables of records no longer count as possibly stale. - The narrow hash is a separate pass in which every wide container (not every argument that holds one) is one tag, so calls that share a wide container but differ elsewhere are told apart without a fresh hash. - The auto-substitute cache first asks the coarse hash whether any entry has objects at the same places (R5TD-2: a distinct first argument per call needs no further work), then the narrow hash. - The search for nested matchers hands the families it found to the hash of the same operation, as it does the keys it listed. - Memo uses are deduplicated per hash; the E19 and R6-ADV-5 ratio tests measure their two cases by turns. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
The R6-ADV-5 ratio test takes the best of six interleaved runs and allows 2x for flat records (74b8588: 3.7x-5x for nested records, which is what it pins); the long tests get a timeout of their own. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…s (R6V-5, R6TD-2, T44) A concrete union member whose variants all return the same type (the addEventListener of every lib.dom element, fetch(url) | fetch(url, options?)) now gets one signature per overload position, whose rest parameter is the union of the variants' parameter lists, computed from the whole member type. The per-variant boxes are only built when the return types differ; intersecting them compared every variant with every other one, which made the union of all element types check 1.6-1.8 times as slowly as before T42 on TypeScript 3.6-3.8. A callback argument without parameter types gets no contextual type there when the variants' callback types differ in more than their this type (pinned in spec-types/limitations.ts). spec-types/R6V-5.R6TD-2.T44.check-cost.js (run by test:types:min-ts) checks a deterministic instantiation budget for the element-union fixture. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…-1, T45)
For concrete unions whose variants return different types, every overload
now gives one signature per number of arguments it accepts (its first n
parameters), whose result also takes what the variants that accept those
arguments return: get('k') of get(key, options?: V1): number and
get(key, options?: V2): string takes number | string, and a call of a
variant with a rest parameter reaches the other variant too. A single
Arg.all() takes what any overload of any variant returns. Signatures without
parameters come last, after the Arg.all() signatures, so that TypeScript 5.3
and older do not pair other signatures with them. Arg.any() and untyped
Arg.is() predicates on parameters whose types differ per variant stay
limited to the first variant's overload (pinned in limitations.ts).
The same-return fast path (T44) now writes each slot's parameters position by
position: TypeScript compared two rest parameters typed as unions of
parameter lists only by their first element and dropped one of the
signatures (postMessage of MessagePort | Worker | BroadcastChannel). It is
taken only for lists of up to 6 parameters without a rest parameter, and in
generic code the boxes are used.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
- An overload whose parameter list is a union of lists (a rest parameter computed from a type parameter, erased to its constraint) stays one overload. It was split into one overload per list, and the member's substitute signatures then became a union that TypeScript paired with the plain signatures of T: a typed emitter's emit() had no setup API, and the configure view was not callable. - A member with a single generic signature also gets a generic signature after all others that takes the arguments the member itself accepts (TypeScript checks them against the generic signature). Node's EventEmitter<Events>.emit, whose erased parameters are never, is then callable, and calls with Arg.any() arguments, which TypeScript's subtype pass used to resolve to the plain generic signature, keep the setup API. Arguments and values of generic methods are checked against the type parameters' constraints (pinned in spec-types/limitations.ts). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
new on a substitute or a member is recorded and answered like a call (E23),
so a type with construct signatures but no call signatures now also gets
call signatures with the constructor's parameters on the substitute, the
configure view and the assertion views: Client('u').returns(client),
Client.received(1)('u'), ns.Client('u').returns(x),
ns.received(1).Client('u'). new keeps the constructor's own typing. On
TypeScript 5.0 and older only the last construct signature of an overloaded
constructor may be matched this way.
The instantiation budget of the T44 cost check is set to 470 000 (the
element-union fixture needs about 442 000 now, 525 000 at 74b8588).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…ints (R6FE-5, R6TD-3, R6TD-4, T48)
- Arg.any('bigint') and Arg.any.not('bigint') are typed (the runtime
accepts 'bigint' officially, E28).
- A concrete union of types with a string index signature is mapped as one
type: its named members with the union of the variants' member types,
next to its string index signature. The homomorphic mapping mapped each
variant on its own, so speak() of IA | IB had the setup API of each
variant's speak and .returns() took never. Generic code keeps T.
- Generic code with a union constraint whose variants declare a method with
different parameter lists has no setup API on TypeScript 5.4 and newer;
pinned as a documented limitation with the configure-view and cast
workarounds.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…l() signatures across variants (T45) The T45 prefix signatures left a variant's own method in the union signatures when one of its parameters has a literal type (TypeScript tries such signatures first): add each overload's whole parameter list to the boxes. The prefix and Arg.all() signatures of variants with the same parameter list are the same types again (call results by the parameter list without names, Arg.all() signatures through an alias), and ReturnsAlike tells return types apart by identity: a union of 60 variants with a `this`-returning method checked 3.3 s instead of 8.4 s on TS 4.5. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…rameter, DOM unions (T45) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…ipt versions have Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…rs (T45) The signature with an overload's whole parameter list is the same as its last prefix signature when the list has no optional parameters; having it twice made TypeScript 3.7 and 3.8 check a union of 60 variants with a `this`-returning method in 24 s instead of 3 s. Empty lists keep it, so that calls without arguments still resolve to the signatures of the variants without parameters first. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…p API (T46) The parameter lists of signatures are no longer split per tuple (T46), which also gives `log(...args: [string] | [string, number])` the setup API, on every supported TypeScript version. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…E18-E21) E18 (R6-ADV-4, R6V-1, R6-ADV-1): memos never change results. A lookup through a possibly stale memoized hash that finds no setup or cached entry looks again with a fresh hash, first the coarse hash and then an exact narrow hash, only where a candidate can exist. An unreadable value is matched by identity for the current operation only, so a value that becomes readable matches an equal setup again. E19 (R6V-3, R6-ADV-3): families stay (a fix-spec perf test needs them), without the membership cache; a family is probed by its lowest and highest key hash, and array items and values inside wide containers are never probed, so small records cost the same with or without families. E20 (R6V-2, R6-ADV-5): a wide object met inside entries or being hashed is listed at most once per operation, and in later operations only its width is checked; the unbounded matcher re-scan runs only for a container seen a second time. E21 (R6-ADV-6, R6-ADV-2): a missing, non-number or below-1 Error.stackTraceLimit captures no frames, as V8 does, and the library never defines or deletes the property. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
E22 (R6FE-2): an omitted trailing argument compares as undefined, so
f(1) and f(1, undefined) match each other and set('a', 1, Arg.any())
matches set('a', 1), while f(1) and f(1, 2) still differ. Trailing
undefined arguments do not change the argument hashes.
E23 (R6FE-3): new on a substitute or a member is a recorded call, shown
as `new Client(args)`; setups and checks written with call syntax apply.
E24 (R6FE-1): auto-substitutes print their path and, when they have
any, their setups and received calls; the root lists nested ones under
their paths.
E25 (R6FE-4): Object.freeze/seal/preventExtensions/defineProperty work
on substitutes and auto-substitutes; short-lived views refuse them with
a SubstituteException.
E26 (R6FE-8): `key in sub` is true for configured keys and keys of a
mimicked instance, false otherwise; it records nothing.
E27 (R6FE-6): '__esModule' is a protocol key.
E28 (R6FE-5): Arg.any(type) and Arg.any.not(type) throw a TypeError for
an unknown type name ('bigint' accepted); mimicks() without a function
throws a TypeError at the setup.
Conflicts: ArgumentHash.ts hashList takes engine B's argumentCount with
engine A's hashValue signature, so the narrow and refined hashes also
ignore trailing undefined arguments; the SubstituteState.ts import is
the union of both branches.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
T43 (R6V-4): members reached through a generic key keep the setup API on TypeScript 4.7 and newer. T44 (R6V-5, R6TD-2): concrete unions whose variants all return the same type take a fast path, so large unions such as all HTML element types check within about 1.2x of 45facfb on TS 3.6-3.8; a cost check pins it. T45 (R6TD-1): union calls resolve by the number of arguments they pass, and take the return types of the variants that accept them; a single Arg.all() takes every variant's return types. T46 (R6FE-7): generic methods (EventEmitter<Events>, typed emitters, find<K>, get<K>) get a usable signature instead of never. T47 (R6FE-3): construct-signature substitutes and constructor members type-check with the call syntax of E23; `new` keeps its typing. T48 (R6FE-5, R6TD-3, R6TD-4): Arg.any('bigint') is typed; unions with a string index signature take the union of return types; the union constraint limitation on TS 5.4+ is pinned. src/api/Arg.ts merged cleanly: engine B's runtime check of the type names and this branch's types and JSDoc both list 'bigint'. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
README:
- `new` on substitutes and members is a call (E23, T47), with an example;
mimicks() validation and construction of classes (E28, E23).
- Matching by type: 'bigint', unknown type names throw (E28); Arg.any('undefined')
matches an omitted argument.
- How arguments are compared: omitted trailing arguments (E22) with an
example; unreadable values are decided per call (E18, R6V-1, R6-ADV-1);
the wide-object hash memo never changes a result, with the
arrange-before-act example (E18, R6-ADV-4); the snippet now prints true.
- Matcher search memo: second-pass re-scan wording (E20, R6-ADV-5).
- Re-configuring a call: the E22 consequence for D5, with an example.
- Stack frames: frozen, sealed and non-extensible Error (R6-ADV-2) and
missing, non-number or below-1 stackTraceLimit (E21, R6-ADV-6), with the
openConnection example under a frozen Error.
- Special members: __esModule (E27), printing of auto-substitutes and
pretty-format (E24), freeze/seal/defineProperty and own keys (E25), the
`in` operator (E26).
- Typing limitations: generic methods (T46), union constraints with
different parameter lists on TS 5.4+ (R6TD-4), call resolution by
argument count and the Arg.any() case (T45), untyped callbacks in large
same-return unions (T44), unions with index signatures (R6TD-3); the
union-of-tuples limitation is gone.
- Debuggers: throwing getters of the code under test; Performance numbers
re-measured on Node.js 22 (best of 3).
MIGRATION: omitted arguments, `new`, printing, freezing and `in`,
__esModule, Arg.any/mimicks validation, the wide-object wording, and the
TypeScript changes. CHANGELOG: the same changes against 2.0.0-beta.4.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
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
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.
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.CHANGELOG.mdlists every user-visible change, andMIGRATION.mdexplains how to upgrade from 1.x and from the betas.The work went through several rounds. Each round fixed the open findings, then re-ran every earlier repro and started fresh adversarial reviews on Node.js 22, 24 and 26. The last review round is still running. Any further fix will come as a new commit here, so the PR stays a draft until then.
What changed
Engine (
src/internals/, rewritten around per-substitute state)Arg.all()), and among setups of the same kind the most recent one wins..call/.apply/.bindorReflect.applyis recorded.app.logger.received().info('hi')) work. Root setups no longer leak into them.sub[configure](),sub[mimick](instance),sub[clearReceivedCalls](), matchers nested inside objects and arrays,Arg.all()after leading arguments, and an exportedSubstituteException.Error.stackTraceLimit = 0, with a read-only or frozenError, with customError.prepareStackTraceformatters (stack-chain, source-map-support), and with fake timers that fakequeueMicrotaskandnextTick.Symbol.iterator,Symbol.hasInstance,then,util.promisify.custom,util.inspect.customand jest's asymmetric-matcher check behave sensibly instead of answering with a substitute.Typings
<T extends Calc>(sub: SubstituteOf<T>));Arg.any('undefined');.mimicks()on union and boolean returns;.not.npm run test:types, plus a TypeScript 3.6 minimum check in CI. The remaining limitations on old TypeScript versions are documented with workarounds in the README's "Typing limitations".Packaging and CI
exportsmap and an ES module entry that shares one copy of the library with CommonJS, so the default import works under native ESM. It is checked with Node and with Rollup/Vite/webpack/esbuild/Rolldown bundles.prepackbuild,enginesverified down to Node 10, and the CI matrix on Node 22/24/26 plus minimum-Node and TypeScript 3.6 jobs.latest/betadist-tag and provenance, and runs after CI. The GitHub Packages job, which could not publish the@fluffy-spoonscope, is removed.Docs
npm run test:docs, 81 blocks).MIGRATION.md,CHANGELOG.md(closes Update documentation #234) andCONTRIBUTING.md.Verification at
74b8588npm testpasses 277 tests on Node 22, 24 and 26.test:types, the TypeScript 3.6 check andtest:docspass.Worth a look before merging
Error.prepareStackTraceis not a function: Node < 20.20 without a formatter, jest 30, and vitestvm*pools. The README gives theskipFilesworkaround.@rollup/plugin-commonjswith the package external, and bundles that emit CommonJS, need the named import or a documented setting. The README and MIGRATION spell this out.Before publishing
NPM_PUBLISH_TOKENmust be a valid granular npm token, or trusted publishing must be configured for the package.v2.0.1GitHub release makes 2.x the npmlatest. Until now,latestis 1.208.0.🤖 Generated with Claude Code
https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt