claude-toolkit 0.16.0 → 0.17.0

package/docs/best-practices/testing/vitest-unit.md

@@ -1,451 +0,0 @@
-# Vitest Unit Testing
-
-> Sources: [Vitest 4.0 Announcement](https://voidzero.dev/posts/announcing-vitest-4), [Vitest 4.1 Blog](https://main.vitest.dev/blog/vitest-4-1), [Vitest Docs](https://vitest.dev/), [SolidJS Testing Docs](https://docs.solidjs.com/guides/testing), [@solidjs/testing-library](https://github.com/solidjs/solid-testing-library)
-
-Unit tests form the base of the testing pyramid. They are fast, isolated, and cover pure logic, reactive primitives, and component behavior in a JSDOM environment.
-
-## AAA Pattern
-
-Every test follows **Arrange-Act-Assert**. Keep each phase visually distinct:
-
-```typescript
-it("should format currency correctly", () => {
-  // Arrange
-  const amount = 1234.5;
-
-  // Act
-  const result = formatCurrency(amount, "NZD");
-
-  // Assert
-  expect(result).toBe("$1,234.50");
-});
-```
-
-For simple tests, the phases can be implicit. For complex tests, add blank lines between them.
-
-## Naming Conventions
-
-- **Files**: `*.test.ts` / `*.test.tsx`, co-located with source or in `tests/`
-- **Describe blocks**: Name the unit under test (`describe("formatCurrency", ...)`)
-- **It blocks**: Describe behavior, not implementation ("should return loading state when resource is pending", not "should set isLoading to true")
-
-## Testing SolidJS Components
-
-### render() Takes a Callback
-
-This is different from React Testing Library. SolidJS needs the callback form to establish a reactive root:
-
-```tsx
-import { render, screen } from "@solidjs/testing-library";
-import { Button } from "../src/components/Button";
-
-it("should render button text", () => {
-  render(() => <Button label="Click me" />);
-  expect(screen.getByRole("button")).toHaveTextContent("Click me");
-});
-```
-
-### Testing Signals with renderHook
-
-For hooks/composables that return reactive state:
-
-```typescript
-import { renderHook } from "@solidjs/testing-library";
-import { useCounter } from "../src/hooks/useCounter";
-
-it("should increment counter", () => {
-  const { result } = renderHook(useCounter);
-  expect(result.count).toBe(0);
-  result.increment();
-  expect(result.count).toBe(1);
-});
-```
-
-### Testing Signals with createRoot
-
-For primitives that don't need component context, `createRoot` is sufficient and faster:
-
-```typescript
-import { createRoot, createSignal, createMemo } from "solid-js";
-
-it("should compute derived value", () => {
-  createRoot((dispose) => {
-    const [count, setCount] = createSignal(0);
-    const doubled = createMemo(() => count() * 2);
-
-    expect(doubled()).toBe(0);
-    setCount(5);
-    expect(doubled()).toBe(10);
-
-    dispose();
-  });
-});
-```
-
-### Testing Effects with testEffect
-
-Effects are async in SolidJS. The `testEffect` utility provides a `done` callback for async assertion:
-
-```typescript
-import { testEffect } from "@solidjs/testing-library";
-import { createSignal, createEffect } from "solid-js";
-
-it("should react to signal changes", () => {
-  const [value, setValue] = createSignal(0);
-
-  return testEffect((done) =>
-    createEffect((run: number = 0) => {
-      if (run === 0) {
-        expect(value()).toBe(0);
-        setValue(1);
-      } else if (run === 1) {
-        expect(value()).toBe(1);
-        done();
-      }
-      return run + 1;
-    })
-  );
-});
-```
-
-### Testing Resources (createResource)
-
-Resources trigger Suspense. Wrap in `<Suspense>` and assert loading/data/error states:
-
-```tsx
-import { render, screen } from "@solidjs/testing-library";
-import { Suspense } from "solid-js";
-
-it("should show loading then data", async () => {
-  render(() => (
-    <Suspense fallback={<div>Loading...</div>}>
-      <MyResourceComponent />
-    </Suspense>
-  ));
-
-  expect(screen.getByText("Loading...")).toBeInTheDocument();
-  expect(await screen.findByText("Data loaded")).toBeInTheDocument();
-});
-```
-
-## Mocking Strategies
-
-### Decision Framework
-
-| Scenario | Tool |
-|---|---|
-| Replace entire module | `vi.mock("module")` |
-| Spy on a specific method | `vi.spyOn(obj, "method")` |
-| Network requests | MSW (`msw/node`) |
-| Vary mock per test | `vi.hoisted` + `mockReturnValue` |
-| Non-hoisted dynamic mock | `vi.doMock` |
-
-### vi.mock with vi.hoisted (Recommended Pattern)
-
-`vi.hoisted` lets you declare mock references that are accessible inside `vi.mock` (which is hoisted to the top of the file):
-
-```typescript
-const { mockFetch } = vi.hoisted(() => ({
-  mockFetch: vi.fn(),
-}));
-
-vi.mock("../src/api/client", () => ({
-  fetchData: mockFetch,
-}));
-
-it("should handle API error", () => {
-  mockFetch.mockRejectedValue(new Error("Network error"));
-  // ... test
-});
-```
-
-### vi.spyOn for Partial Mocking
-
-When you only need to intercept one method while keeping the rest real:
-
-```typescript
-import * as utils from "../src/utils";
-
-it("should call logger", () => {
-  const spy = vi.spyOn(utils, "log");
-  doSomething();
-  expect(spy).toHaveBeenCalledWith("action completed");
-  spy.mockRestore();
-});
-```
-
-### MSW for Network Mocking
-
-Mock Service Worker intercepts at the network level, giving realistic integration tests:
-
-```typescript
-import { setupServer } from "msw/node";
-import { http, HttpResponse } from "msw";
-
-const server = setupServer(
-  http.get("/api/user", () => HttpResponse.json({ name: "Alice" }))
-);
-
-beforeAll(() => server.listen());
-afterEach(() => server.resetHandlers());
-afterAll(() => server.close());
-
-it("should display user name", async () => {
-  render(() => <UserProfile />);
-  expect(await screen.findByText("Alice")).toBeInTheDocument();
-});
-```
-
-### mockThrow / mockThrowOnce (Vitest 4.1+)
-
-Concise error path testing without wrapping in functions:
-
-```typescript
-mockFn.mockThrow(new Error("failed"));
-mockFn.mockThrowOnce(new Error("first call fails"));
-```
-
-### Type-Safe Mocks
-
-Use `vi.mocked()` for typed access to mocked functions:
-
-```typescript
-import { fetchUser } from "../src/api";
-vi.mock("../src/api");
-
-const mockedFetchUser = vi.mocked(fetchUser);
-mockedFetchUser.mockResolvedValue({ name: "Alice" });
-```
-
-## Snapshot Testing
-
-### When to Use
-
-- Serialized objects, API response shapes, configuration objects
-- Small component output (buttons, cards, form fields)
-
-### When NOT to Use
-
-- Large pages or complex component trees
-- Frequently changing UI
-- Dynamic content (timestamps, IDs, random values)
-
-### Prefer Inline Snapshots
-
-Keeps expected output visible in the test file:
-
-```typescript
-expect(formatUser(user)).toMatchInlineSnapshot(`
-  {
-    "name": "Alice",
-    "role": "admin",
-  }
-`);
-```
-
-### Handle Dynamic Values
-
-```typescript
-expect(result).toMatchObject({
-  id: expect.any(String),
-  createdAt: expect.any(Date),
-  name: "Alice",
-});
-```
-
-### Snapshot Hygiene
-
-- Review snapshot diffs as carefully as code diffs in PRs
-- Run `vitest --update` only intentionally, never blindly
-- CI should fail on obsolete snapshots
-
-## Type Testing
-
-Vitest has built-in type testing (since 2.1). Verify your types work correctly alongside runtime:
-
-```typescript
-import { expectTypeOf } from "vitest";
-
-it("should return correct type", () => {
-  const result = parseConfig(rawConfig);
-  expectTypeOf(result).toEqualTypeOf<AppConfig>();
-  expectTypeOf(result.port).toBeNumber();
-});
-```
-
-## Coverage
-
-### Use V8 Provider
-
-Since Vitest 3.2, V8 coverage uses AST-based remapping that matches Istanbul accuracy with ~10% overhead vs Istanbul's ~300%. Always use V8:
-
-```typescript
-// vite.config.ts
-test: {
-  coverage: {
-    provider: "v8",
-    include: ["src/**/*.{ts,tsx}"],
-    exclude: [
-      "src/**/*.css.ts",      // vanilla-extract style files
-      "src/**/index.ts",       // barrel exports
-      "src/**/*.d.ts",         // type declarations
-      "src/locales/**",        // i18n generated files
-    ],
-    reporter: ["text", "html", "lcov"],
-    thresholds: {
-      statements: 80,
-      branches: 70,
-      functions: 80,
-      lines: 80,
-    },
-  },
-}
-```
-
-### Coverage Recommendations
-
-- Start with moderate thresholds (70-80%) and ratchet up as coverage grows
-- Focus on **branch coverage** -- it catches more real bugs than line coverage
-- Use per-glob overrides for critical paths (e.g., `src/utils/**` at 95%)
-- Use `/* v8 ignore start */` / `/* v8 ignore stop */` for intentionally uncovered code
-
-## Vitest 4.x Features
-
-### Test Tags
-
-Define tags with per-tag configuration. Useful for separating fast/slow tests:
-
-```typescript
-// vite.config.ts
-test: {
-  tags: {
-    slow: { timeout: 30_000 },
-    flaky: { retry: 3 },
-  },
-}
-```
-
-```typescript
-it.tags(["slow"])("should process large dataset", async () => {
-  // ...
-});
-```
-
-### Builder-Pattern Fixtures
-
-The idiomatic way to share setup in Vitest 4.x. TypeScript infers fixture types automatically:
-
-```typescript
-const myTest = test
-  .extend({ config: { timeout: 5000 } })
-  .extend({
-    server: async ({ config }, { onCleanup }) => {
-      const srv = await startServer(config);
-      onCleanup(() => srv.close());
-      return srv;
-    },
-  });
-
-myTest("should connect to server", ({ server }) => {
-  expect(server.isRunning()).toBe(true);
-});
-```
-
-### Detect Async Leaks
-
-Reports leaked async resources with source locations. Enable while debugging:
-
-```typescript
-test: {
-  detectAsyncLeaks: true, // Disable in CI (adds overhead)
-}
-```
-
-## Performance
-
-### Pool Configuration
-
-| Pool | Best For |
-|---|---|
-| `threads` (default) | General use, SolidJS + JSDOM tests |
-| `forks` | Better isolation, more overhead |
-| `vmThreads` | VM contexts with worker parallelism |
-
-### Sharding for CI
-
-Split tests across CI machines:
-
-```bash
-# Machine 1
-vitest run --shard=1/3 --reporter=blob
-
-# Machine 2
-vitest run --shard=2/3 --reporter=blob
-
-# Machine 3
-vitest run --shard=3/3 --reporter=blob
-
-# Merge
-vitest merge-reports
-```
-
-### Other Tips
-
-- Use `test.concurrent` for independent async tests
-- Keep test files small and focused (Vitest parallelizes at the file level)
-- Avoid heavy setup in `beforeAll` that could be lazy-loaded
-- Use `--no-isolate` only for pure function test files, never for component tests
-
-## Recommended Config
-
-```typescript
-// vite.config.ts (test section)
-test: {
-  environment: "jsdom",
-  globals: true,
-  setupFiles: ["./tests/setup.ts"],
-  include: ["src/**/*.test.{ts,tsx}", "tests/**/*.test.{ts,tsx}"],
-  restoreMocks: true,
-  coverage: {
-    provider: "v8",
-    include: ["src/**/*.{ts,tsx}"],
-    exclude: [
-      "src/**/*.css.ts",
-      "src/**/index.ts",
-      "src/**/*.d.ts",
-      "src/locales/**",
-    ],
-    reporter: ["text", "html", "lcov"],
-    thresholds: {
-      statements: 80,
-      branches: 70,
-      functions: 80,
-      lines: 80,
-    },
-  },
-}
-```
-
-```typescript
-// tests/setup.ts
-import "@testing-library/jest-dom/vitest";
-
-afterEach(() => {
-  vi.clearAllTimers();
-});
-```
-
-## Anti-Patterns
-
-| Anti-Pattern | Fix |
-|---|---|
-| Testing implementation details (internal state, private methods) | Test behavior and public API only |
-| Large snapshots (100+ lines) | Break into small focused snapshots or use explicit assertions |
-| Blind `--update` on snapshot failures | Review each diff individually |
-| `vi.mock` without cleanup | Enable `restoreMocks: true` in config |
-| Shared mutable state across tests | Reset state in `beforeEach` or use fixtures |
-| Testing framework code (that SolidJS reactivity works) | Test your logic, not the framework |
-| `setTimeout` in tests for async waits | Use `waitFor`, `findBy*`, or `vi.advanceTimersByTime` |
-| Over-mocking (mocking everything) | Mock only external boundaries (network, timers, platform APIs) |
-| Destructuring SolidJS props in tests | Same rule as production -- never destructure props |
-| Using `as any` in test code | If you need it, the API under test is wrong |

package/docs/best-practices/typescript/README.md

@@ -1,45 +0,0 @@
-# Matt Pocock's TypeScript Best Practices
-
-> A curated collection of TypeScript best practices, opinions, and patterns from [Matt Pocock](https://www.mattpocock.com/) and [Total TypeScript](https://www.totaltypescript.com/).
-
-Matt Pocock is one of the most influential TypeScript educators. These documents capture his opinionated, production-tested guidance — not generic advice, but specific stances backed by reasoning.
-
-## Core Choices
-
-Foundational decisions that shape every TypeScript project.
-
-| Guide | Summary |
-|---|---|
-| [Type vs Interface](type-vs-interface.md) | Default to `type`. Use `interface` only for `extends`. |
-| [Enums & Alternatives](enums-alternatives.md) | Avoid enums. Use `as const` objects with derived unions. |
-| [any & unknown](any-and-unknown.md) | Ban `any` by default. Know the two legitimate exceptions. |
-| [TSConfig Cheat Sheet](tsconfig-cheat-sheet.md) | Recommended compiler options for every project shape. |
-
-## Patterns
-
-Type-level patterns that make code safer and more expressive.
-
-| Guide | Summary |
-|---|---|
-| [Discriminated Unions](discriminated-unions.md) | Model states as unions — make illegal states unrepresentable. |
-| [Generics Patterns](generics-patterns.md) | Three patterns: types-to-types, types-to-functions, inference. |
-| [The `satisfies` Operator](satisfies-operator.md) | Five practical uses for type validation without losing inference. |
-| [Essential Patterns](essential-patterns.md) | Branded types, globals, assertion functions, classes. |
-
-## Architecture
-
-How to organize and connect types across a codebase.
-
-| Guide | Summary |
-|---|---|
-| [Type Organization](type-organization.md) | Colocate, share at folder level, or extract to a package. |
-| [Deriving vs Decoupling](deriving-vs-decoupling.md) | Derive when tightly coupled. Decouple across concerns. |
-| [Runtime Validation](runtime-validation.md) | Use Zod at trust boundaries. Skip it for controlled inputs. |
-
-## Micro-Opinions
-
-Small but specific stances on everyday TypeScript choices.
-
-| Guide | Summary |
-|---|---|
-| [Micro-Opinions](micro-opinions.md) | Return types, `const` vs `let`, `T[]` vs `Array<T>`, method shorthand, `Function` type. |

package/docs/best-practices/typescript/any-and-unknown.md

@@ -1,73 +0,0 @@
-# `any` & `unknown`
-
-> Source: [any Considered Harmful, Except For These Cases](https://www.totaltypescript.com/any-considered-harmful) — Matt Pocock
-
-## The Rule
-
-**Ban `any` from your codebase.** Enable the ESLint rule that prevents its use and avoid it wherever possible.
-
-`any` disables TypeScript's core value proposition: type checking, autocomplete, and safety guarantees. It's a contagion — once `any` enters an expression, it spreads through assignments and return values.
-
-## What to Use Instead
-
-| Situation | Use |
-|---|---|
-| Type is genuinely unknown | `unknown` (then narrow before use) |
-| Type varies but has a consistent shape | Generics with constraints |
-| You know the data shape | The specific type |
-
-```typescript
-// Instead of any
-function parse(input: unknown): User {
-  if (typeof input === "object" && input !== null && "name" in input) {
-    return input as User;
-  }
-  throw new Error("Invalid input");
-}
-```
-
-## The Two Legitimate Exceptions
-
-Matt identifies two advanced scenarios where `any` is the right choice.
-
-### Exception 1: Type Argument Constraints in Generics
-
-When building generic utility types, `unknown` in constraints can be too restrictive:
-
-```typescript
-// This is too restrictive — only works with specific function shapes
-type ReturnType<T extends (...args: unknown[]) => unknown> = ...
-
-// any[] constraint is correct — "we don't care what the function accepts"
-type ReturnType<T extends (...args: any[]) => any> = ...
-```
-
-Using `any[]` here is intentional: you're declaring that the constraint should accept **any function**, not that you're bypassing safety.
-
-### Exception 2: Conditional Types in Generic Functions
-
-TypeScript's type narrowing sometimes can't verify that conditional type logic matches runtime behavior:
-
-```typescript
-function processValue<T extends string | number>(
-  value: T
-): T extends string ? string[] : number {
-  if (typeof value === "string") {
-    return value.split("") as any; // TypeScript can't narrow conditional return types
-  }
-  return (value as number) * 2 as any;
-}
-```
-
-In these cases, Matt recommends using `as any` **and adding a unit test** to validate the function's behavior at runtime.
-
-## The Pragmatic Approach
-
-When you genuinely need `any`, use an `eslint-disable` comment to make it explicit and reviewable:
-
-```typescript
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type Callback = (...args: any[]) => void;
-```
-
-This creates a searchable record of every `any` in your codebase, making them easy to audit and justify in code review.

package/docs/best-practices/typescript/deriving-vs-decoupling.md

@@ -1,83 +0,0 @@
-# Deriving vs Decoupling
-
-> Source: [Deriving vs Decoupling: When NOT To Be A TypeScript Wizard](https://www.totaltypescript.com/deriving-vs-decoupling) — Matt Pocock
-
-## The Distinction
-
-- **Deriving** = creating a type that depends on another type's structure (`Pick`, `Omit`, `typeof`, mapped types)
-- **Decoupling** = creating independent types with no dependency between them
-
-The temptation to derive comes from TypeScript's powerful type manipulation. But cleverness isn't always correctness.
-
-## When to Decouple
-
-Decouple when types serve **different concerns** — different responsibilities with different reasons to change.
-
-```typescript
-// Database layer
-type User = {
-  id: string;
-  name: string;
-  email: string;
-  imageUrl: string;
-  passwordHash: string;
-};
-
-// UI layer — DON'T derive from User
-type AvatarProps = {
-  imageUrl: string;
-  name: string;
-};
-```
-
-Why not `Pick<User, "imageUrl" | "name">`? Because:
-- `User` lives in database code; `AvatarProps` is UI logic
-- They have different reasons to change
-- If `User.imageUrl` is renamed to `User.avatarUrl`, should every UI component break? Probably not.
-- The component should remain portable even if the data model moves
-
-As Matt puts it: "It's smarter to do the simple thing."
-
-## When to Derive
-
-Derive when types share a **common concern** and are tightly coupled by design.
-
-### From `as const` objects
-
-```typescript
-const albumTypes = {
-  CD: "cd",
-  VINYL: "vinyl",
-  DIGITAL: "digital",
-} as const;
-
-type AlbumType = (typeof albumTypes)[keyof typeof albumTypes];
-// "cd" | "vinyl" | "digital"
-```
-
-Maintaining a separate union and object would mean updating two places for every change — pure busywork.
-
-### Related variants
-
-```typescript
-type User = {
-  id: string;
-  name: string;
-  email: string;
-};
-
-type UserWithoutId = Omit<User, "id">;
-```
-
-These are directly related — a `UserWithoutId` is meaningless outside the context of `User`.
-
-## Decision Framework
-
-> "The decision to derive or decouple is all about reducing your future workload."
-
-| Signal | Action |
-|---|---|
-| Changing one type should always change the other | **Derive** |
-| Types serve different layers or concerns | **Decouple** |
-| Derivation adds complexity for marginal DRY benefit | **Decouple** |
-| Types share the same source of truth | **Derive** |