feat!: constrain stub<T> method names to keyof T

[jamlen]

Closes #127.

stub<T>(methodNames) looked like it constrained names to keyof T but didn't — two overloads were reachable and the second accepted any string[], so a typo compiled and produced a mock silently missing that method.

What changed

The name-list overload is now the single checked form, and is declared before the object overload rather than after it:

export function stub<I extends object>(cls: new (...args: never[]) => I): Wrapped<I>
export function stub<T extends object = Record<string, unknown>>(
  methodNames: readonly (keyof T)[],
  properties?: StubPropertyDescriptor[],
  options?: StubOptions
): Wrapped<T>
export function stub<T extends object>(obj: T): Wrapped<T>

Three defects fixed

1. The reported one. Names are checked against keyof T:

Type '"sve"' is not assignable to type 'keyof AccountGateway'. Did you mean '"save"'?

2. Overload order — arguably the bigger bug. An array is also an object, so stub(['query','close']) with no type argument bound T to string[] and keyed the facades off Array members: you got setup.length and setup.push, not setup.query. The names now infer into the mock's shape, so setup.query and expect.close type-check. This was not in the issue.

3. readonly / as const name lists are accepted; they failed both before and under the fix as #127 proposed it.

Why reordering rather than the issue's proposal

I probed excluding arrays from the object overload with a conditional type (T extends readonly unknown[] ? never : T). It constrains correctly but breaks generic helpers that wrap stub():

function makeMock<U extends object>(o: U) { return stub(o) }   // fails

Reordering achieves the same result with no conditional and no generic-context regression. There's a guard for this case in test/type-check.ts.

Verification

Verified against tsc 6.0.3:

Call	Before	After
stub<Gw>(['get','sve'])	compiles	errors, suggests "save"
stub<Gw>(['get','save'])	compiles	compiles
stub<Gw>(['get','save'] as const)	errors	compiles
stub<Gw>(['get']) (subset)	compiles	compiles
stub(['query','close'])	Wrapped<string[]>	Wrapped<{query,close}>
stub<Gw>(dynamicStringArray)	compiles	errors (see below)
makeMock<U>(o) generic helper	compiles	compiles

Guards live in test/type-check.ts — the only test file tsconfig.json compiles, so a guard in test/types.test.ts would never run in CI. Plus 4 runtime tests in test/stub.test.ts.

pnpm lint, pnpm typecheck, 540 tests, coverage (95.33% statements / 88.93% branches, both above threshold), pnpm build, and pnpm docs:build all pass. Also fixed the internal stub.class call site the issue didn't mention.

What this does NOT fix

Exhaustiveness. The check is that supplied names exist on T, not that all of T is covered — stub<Gw>(['get']) still compiles while Wrapped<Gw> claims save exists. Partial stubs are a deliberate, supported pattern (test/type-check.ts:13 relies on one). Enforcing coverage would break far more than it fixes. This is documented instead, in common-mistakes.md §16.

Breaking change

Values typed string[] are rejected. Correct literal lists are unaffected — this only bites lists built at runtime, which opt out explicitly:

const names: string[] = readMethodsFromConfig()
stub<Database>(names as (keyof Database)[])

Per the discussion on #127 this is a documented cast rather than new API surface. Code relying on the old Wrapped<string[]> inference will surface type errors, since the mock is now typed from the names.

Runtime behaviour is unchanged — this is type-level only.

Docs

Synced per CLAUDE.md's table: ai/decision-tree.md (factory row + runtime-list row), ai/common-mistakes.md (two new entries), api/stub.md, guide/creating-mocks.md, guide/typescript.md, and a v2→v3 section in guide/migrating.md.

Note guide/creating-mocks.md claimed "Every method on T must appear in the array; TypeScript checks it" — wrong before this change and still wrong after (it checks existence, not exhaustiveness). Corrected.

⚠️ This cannot release until #134 is resolved — NPM_TOKEN is invalid and verifyConditions will fail. This is a feat! so it would publish v3.0.0.

🤖 Generated with Claude Code

[jamlen]

Holding this pending the outcome of #142.

Merging this to main publishes v3.0.0 immediately — release.yml fires on every push to main, this squashes to a feat!: commit, and the OIDC path now works, so nothing gates it. The merge is the release.

#142 proposes gating breaking changes behind a next prerelease branch. If that's adopted, this PR retargets to next and ships as 3.0.0-next.1 on the next dist-tag first, which removes the one-shot risk. If it's declined, this merges to main and cuts v3.0.0 directly — in which case the docs and README work in #142's "alternative" section needs to land first.

No changes needed to the code here either way; it's green on all 13 checks.