@ranimontagna/agent-toolkit 0.1.6 → 0.1.7

package/skills/frontend/react/react-patterns/rules/react/testing.md

@@ -0,0 +1,208 @@
+---
+paths:
+  - "**/*.test.tsx"
+  - "**/*.test.jsx"
+  - "**/*.spec.tsx"
+  - "**/*.spec.jsx"
+  - "**/__tests__/**/*.ts"
+  - "**/__tests__/**/*.tsx"
+---
+# React Testing
+
+> This file extends the upstream `typescript/testing.md` and `common/testing.md` rules with React specific content.
+
+## Library Choice
+
+- **React Testing Library (RTL)** — the standard for component testing. Tests behavior through the rendered DOM.
+- **Vitest** — preferred runner for new Vite-based projects. Faster than Jest, native ESM, same API.
+- **Jest** — still the default for Next.js / CRA projects. RTL works identically.
+- **Playwright Component Testing** — when component tests need a real browser engine (animation, layout, complex events)
+- **Cypress Component Testing** — alternative real-browser component runner
+
+Pick one component test runner per project — do not mix RTL + Playwright CT in the same repo.
+
+## Core Principle
+
+Test what the user sees and does, not implementation details.
+
+- Query by accessible role first, then label, then text — fall back to `data-testid` only when nothing else fits
+- Never assert on internal state, props passed to children, or which hooks were called
+- Refactor without breaking tests = the test was testing behavior; that is the goal
+
+## Query Priority
+
+RTL exposes queries in three families. Use this priority order top-down:
+
+1. **Accessible to everyone**
+   - `getByRole(role, { name })` — primary choice
+   - `getByLabelText` — for form inputs
+   - `getByPlaceholderText` — when no label is available (and add a label)
+   - `getByText` — for non-interactive text
+   - `getByDisplayValue` — for form fields with a current value
+
+2. **Semantic queries**
+   - `getByAltText` — for images
+   - `getByTitle` — last resort, low accessibility value
+
+3. **Test IDs**
+   - `getByTestId("some-id")` — escape hatch only, when none of the above work
+
+`getBy*` throws when no match. `queryBy*` returns null (use for asserting absence). `findBy*` returns a promise (use for async).
+
+## User Interaction
+
+Prefer `userEvent` over `fireEvent`. `userEvent` simulates real browser sequences (focus, keydown, beforeinput, input, keyup) — `fireEvent` dispatches a single synthetic event.
+
+```tsx
+import userEvent from "@testing-library/user-event";
+
+test("submits the form", async () => {
+  const user = userEvent.setup();
+  render(<UserForm onSubmit={handleSubmit} />);
+
+  await user.type(screen.getByLabelText("Email"), "user@example.com");
+  await user.click(screen.getByRole("button", { name: /save/i }));
+
+  expect(handleSubmit).toHaveBeenCalledWith({ email: "user@example.com" });
+});
+```
+
+- Always `await` `userEvent` calls — they are async
+- Call `userEvent.setup()` once at the top of each test, then reuse the returned `user`
+
+## Async Assertions
+
+```tsx
+// WRONG: synchronous query for async-rendered content
+expect(screen.getByText("Loaded")).toBeInTheDocument();   // throws — not in DOM yet
+
+// CORRECT: findBy* (returns a promise, retries)
+expect(await screen.findByText("Loaded")).toBeInTheDocument();
+
+// CORRECT: waitFor for non-element assertions
+await waitFor(() => expect(saveSpy).toHaveBeenCalled());
+```
+
+- `findBy*` for async element appearance
+- `waitFor` for async expectations on side effects or other matchers
+- Never `setTimeout` + assertion — flaky
+
+## Network Mocking with MSW
+
+Use Mock Service Worker for any test that hits a network boundary. MSW runs at the network layer, so the component, hooks, and fetch library all behave as in production.
+
+```tsx
+// test setup
+import { setupServer } from "msw/node";
+import { http, HttpResponse } from "msw";
+
+const server = setupServer(
+  http.get("/api/users/:id", ({ params }) =>
+    HttpResponse.json({ id: params.id, name: "Alice" }),
+  ),
+);
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+Per-test override:
+
+```tsx
+test("renders error on 500", async () => {
+  server.use(http.get("/api/users/:id", () => new HttpResponse(null, { status: 500 })));
+  render(<UserPage id="1" />);
+  expect(await screen.findByText(/something went wrong/i)).toBeInTheDocument();
+});
+```
+
+## Avoid Snapshot Tests for Components
+
+Snapshots of rendered output are brittle, hard to review, and rubber-stamped by reviewers. Use them only for:
+
+- Pure data serialization (e.g., a transformer that produces a stable string)
+- Catching unintended regressions in non-visual output
+
+For component visual regression, use Playwright / Cypress / Percy screenshots — actual visual diffs, not DOM diffs.
+
+## Test Setup Helpers
+
+Wrap providers once:
+
+```tsx
+function renderWithProviders(ui: React.ReactElement) {
+  return render(
+    <QueryClientProvider client={new QueryClient()}>
+      <ThemeProvider theme={lightTheme}>
+        <Router>{ui}</Router>
+      </ThemeProvider>
+    </QueryClientProvider>,
+  );
+}
+```
+
+Export from `test-utils.tsx` and use everywhere.
+
+## Custom Hook Testing
+
+Use `renderHook` from RTL:
+
+```tsx
+import { renderHook, act } from "@testing-library/react";
+
+test("useCounter increments", () => {
+  const { result } = renderHook(() => useCounter());
+  act(() => result.current.increment());
+  expect(result.current.count).toBe(1);
+});
+```
+
+- Always wrap state-changing calls in `act`
+- Always test through the public hook API, not internal implementation
+
+## Accessibility Assertions
+
+```tsx
+import { axe } from "vitest-axe";   // or jest-axe
+
+test("UserCard has no a11y violations", async () => {
+  const { container } = render(<UserCard user={mockUser} />);
+  expect(await axe(container)).toHaveNoViolations();
+});
+```
+
+Run axe assertions in component tests — catches missing labels, ARIA misuse, color contrast (limited).
+
+## When to Reach for Playwright / Cypress
+
+Component test with RTL + JSDOM cannot:
+
+- Test real layout (flexbox, grid, viewport-dependent rendering)
+- Test scrolling, drag-and-drop, paste from clipboard
+- Test browser-native animation, CSS transitions
+- Test cross-frame interactions (iframes, popups)
+
+For those, use Playwright Component Testing or end-to-end Playwright/Cypress runs. See the e2e-testing skill when it is installed.
+
+## Coverage Targets
+
+| Layer | Target |
+|---|---|
+| Pure utility functions | ≥90% |
+| Custom hooks | ≥85% |
+| Components (presentational) | ≥80% — behavior, not lines |
+| Container components | ≥70% — golden paths + error states |
+| Pages (E2E covered separately) | Smoke test per route minimum |
+
+## Anti-Patterns
+
+- Asserting on `container.querySelector` — bypasses accessibility queries
+- Asserting on number of renders — implementation detail
+- Mocking React hooks (`jest.mock("react", ...)`) — refactor the component instead
+- Mocking child components by default — tests the integration, not the parent in isolation
+- Manual `act()` warnings ignored — they indicate real bugs
+
+## Skill Reference
+
+See `skills/react-testing/SKILL.md` for end-to-end test examples, MSW patterns, and accessibility test scaffolding.

package/skills/frontend/react/react-performance/SKILL.md

@@ -562,8 +562,8 @@ When the project ships React Compiler, demote `rerender-*` manual memoization ru
 
 ## Related
 
-- Skills: [react-patterns](../react-patterns/SKILL.md), [react-testing](../react-testing/SKILL.md), [frontend-patterns](../frontend-patterns/SKILL.md), [accessibility](../accessibility/SKILL.md), [nextjs-turbopack](../nextjs-turbopack/SKILL.md)
-- Rules: [rules/react/](../../rules/react/)
+- Skills: [react-patterns](../react-patterns/SKILL.md), [react-testing](../react-testing/SKILL.md), frontend-patterns, accessibility, nextjs-turbopack
+- Rules: [rules/react/](rules/react/)
 - Agents: `react-reviewer` enforces these rules in code review; `react-build-resolver` handles related build failures
 - Commands: `/react-review`, `/react-build`, `/react-test`
 

package/skills/frontend/react/react-performance/rules/react/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/frontend/react/react-performance/rules/react/NOTICE.md

@@ -0,0 +1,11 @@
+# Third-party notice
+
+This directory contains React rule references copied from Affaan Mustafa's ECC
+repository.
+
+- Source: https://github.com/affaan-m/ECC/tree/main/rules/react
+- Source commit: 0f84c0e2796703fbda87d577b2636351418c7442
+- License: MIT
+- Copyright: Copyright (c) 2026 Affaan Mustafa
+
+The upstream MIT license is included in `LICENSE`.

package/skills/frontend/react/react-performance/rules/react/coding-style.md

@@ -0,0 +1,109 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/components/**/*.ts"
+  - "**/components/**/*.js"
+  - "**/hooks/**/*.ts"
+  - "**/hooks/**/*.js"
+---
+# React Coding Style
+
+> This file extends the upstream `typescript/coding-style.md` and `common/coding-style.md` rules with React specific content.
+
+## File Extensions
+
+- `.tsx` for any file containing JSX, even one-liner snippets
+- `.ts` for pure logic, custom hooks without JSX, type definitions, utilities
+- `.test.tsx` / `.test.ts` mirroring the source file
+- Use `.jsx` only when the project intentionally avoids TypeScript — flag every new untyped React file in review
+
+## Naming
+
+- Components: `PascalCase` for both the symbol and the file (`UserCard.tsx`, default export `UserCard`)
+- Custom hooks: `useCamelCase` for the symbol, kebab-case for the file when the project convention is kebab-case (`use-debounce.ts` exports `useDebounce`)
+- Context: `<Domain>Context` symbol, `<Domain>Provider` provider component, `use<Domain>` consumer hook
+- Event handlers: `handleClick`, `handleSubmit` inside the component; the prop that receives it is `onClick`, `onSubmit`
+- Boolean props: `isLoading`, `hasError`, `canSubmit` — never `loading` or `error` alone for booleans
+
+## Component Shape
+
+```tsx
+type Props = {
+  user: User;
+  onSelect: (id: string) => void;
+};
+
+export function UserCard({ user, onSelect }: Props) {
+  return (
+    <button type="button" onClick={() => onSelect(user.id)}>
+      {user.name}
+    </button>
+  );
+}
+```
+
+- Prefer `type Props = {}` for closed component prop shapes
+- Use `interface` only when the prop type is extended via declaration merging or exported as a public API extension point
+- Always destructure props in the parameter list — no `props.user` access inside the body
+- Type the return implicitly through JSX (`function Foo(): JSX.Element` only when the function returns conditionally and the union confuses inference)
+
+## JSX
+
+- Self-close tags with no children: `<img />`, `<UserCard user={u} />`
+- Use fragments `<>...</>` over wrapper `<div>` when no DOM element is needed
+- Conditional rendering: `{condition && <Foo />}` for booleans, ternary for either/or, early return for guard clauses
+- Never put logic inline in JSX when it reads as multi-line — extract to a const above the return or a function
+
+```tsx
+// Prefer
+const greeting = user.isAdmin ? "Welcome, admin" : `Hello ${user.name}`;
+return <h1>{greeting}</h1>;
+
+// Over
+return <h1>{user.isAdmin ? "Welcome, admin" : `Hello ${user.name}`}</h1>;
+```
+
+## Server / Client Boundary (Next.js App Router, RSC)
+
+- Default a new file to Server Component — only add `"use client"` when the file uses state, effects, refs, browser APIs, or event handlers
+- Place the `"use client"` directive on line 1, before any imports
+- Never import a Client Component file from inside a `"use server"` action file
+- Never re-export server-only code through a client module — the bundler will silently include it
+
+## Imports
+
+- React imports first: `import { useState } from "react"`
+- Then third-party libs, then absolute project imports, then relative
+- Type-only imports: `import type { ReactNode } from "react"` — never mix runtime and type imports in one statement when ESLint's `consistent-type-imports` is configured
+
+## Hooks Discipline
+
+See [hooks.md](./hooks.md) for the full ruleset. Style highlights:
+
+- Custom hooks must start with `use` — enforced by `eslint-plugin-react-hooks`
+- Group all hook calls at the top of the component, before any conditional logic
+- Avoid creating ad-hoc hooks for one-line wrappers — inline the call instead
+
+## State
+
+- Local first (`useState`), lift only when shared
+- Context for cross-cutting state read by many components (theme, auth, i18n) — not for high-frequency updates
+- External store (Zustand, Jotai, Redux Toolkit) when state must persist across route changes, sync across tabs, or be debugged via devtools
+- Never duplicate state that can be derived — compute during render
+
+## Class Components
+
+Forbidden in new code. Convert legacy class components to function components when touching them for non-trivial changes.
+
+## File Layout per Component
+
+```
+components/UserCard/
+  UserCard.tsx
+  UserCard.module.css   # or styled-components, or Tailwind classes inline
+  UserCard.test.tsx
+  index.ts              # re-export only
+```
+
+Inline single-file components are fine for trivial presentational pieces.

package/skills/frontend/react/react-performance/rules/react/hooks.md

@@ -0,0 +1,187 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/hooks/**/*.ts"
+  - "**/hooks/**/*.js"
+  - "**/use-*.ts"
+  - "**/use-*.tsx"
+---
+# React Hooks
+
+> This file covers **React hooks** (`useState`, `useEffect`, `useMemo`, `useCallback`, custom hooks) — NOT the Claude Code `hooks/` runtime system. Naming matches the per-language convention `rules/<lang>/hooks.md` used across this repo.
+>
+> Extends the upstream `typescript/patterns.md` and `common/patterns.md` rules.
+
+## Rules of Hooks
+
+Enforce `eslint-plugin-react-hooks` with `react-hooks/rules-of-hooks` set to error.
+
+1. Hooks only at the top level of a function component or another hook
+2. Never in loops, conditionals, nested functions, or after early returns
+3. Always called in the same order on every render
+4. Only inside React function components or custom hooks (functions starting with `use`)
+
+```tsx
+// WRONG: conditional hook
+function Foo({ enabled }: { enabled: boolean }) {
+  if (enabled) {
+    const [x, setX] = useState(0); // rule violation
+  }
+}
+
+// CORRECT: hook unconditional, condition inside
+function Foo({ enabled }: { enabled: boolean }) {
+  const [x, setX] = useState(0);
+  if (!enabled) return null;
+  return <span>{x}</span>;
+}
+```
+
+## `useEffect` — When NOT to Use
+
+`useEffect` is for synchronizing with external systems (subscriptions, browser APIs, third-party libraries). It is **not** the right tool for:
+
+- Derived state — compute it during render
+- Transforming data for rendering — compute it during render
+- Resetting state when a prop changes — use a `key` on the parent or derive from props
+- Notifying parents of state changes — call the callback in the event handler
+- Initializing app-level singletons — call the function module-side or in `main.tsx`
+
+```tsx
+// WRONG: effect for derived state
+const [fullName, setFullName] = useState("");
+useEffect(() => {
+  setFullName(`${first} ${last}`);
+}, [first, last]);
+
+// CORRECT: derive during render
+const fullName = `${first} ${last}`;
+```
+
+## Dependency Arrays
+
+- Always include every reactive value referenced inside the effect/callback
+- Enable `react-hooks/exhaustive-deps` lint rule — never silence it without a comment explaining why
+- If the dep array grows unwieldy, the effect is doing too much — split it
+- Stable identity for functions passed in deps: wrap in `useCallback` only when the function is itself a dependency of another hook or passed to a memoized child
+
+## Cleanup
+
+Every subscription, interval, listener, or in-flight request must clean up.
+
+```tsx
+useEffect(() => {
+  const controller = new AbortController();
+  fetch(url, { signal: controller.signal }).then(handleResponse);
+  return () => controller.abort();
+}, [url]);
+```
+
+```tsx
+useEffect(() => {
+  const id = setInterval(tick, 1000);
+  return () => clearInterval(id);
+}, []);
+```
+
+Missing cleanup = race conditions when deps change, memory leaks on unmount.
+
+## `useMemo` and `useCallback` — When Worth It
+
+Default position: **do not memoize**. Add `useMemo` / `useCallback` only when:
+
+1. The value is passed to a `React.memo`-wrapped child as a prop, and identity matters
+2. The value is a dependency of another `useEffect` / `useMemo` / `useCallback`
+3. The computation is measurably expensive (profile before assuming)
+
+Premature memoization adds noise, hides bugs, and can be slower than the recompute it replaces.
+
+## Custom Hooks
+
+Extract a custom hook when:
+
+- The same hook sequence (state + effect + computed) appears in 2+ components
+- The logic has a clear, nameable purpose (`useDebounce`, `useOnClickOutside`, `useLocalStorage`)
+- You want to test the logic independently of any component
+
+Do NOT extract when:
+
+- It would have a single caller — inline it
+- The "hook" is just `useState` with a different name — adds indirection, no value
+
+```tsx
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const id = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(id);
+  }, [value, delay]);
+  return debounced;
+}
+```
+
+## `useState` Patterns
+
+- Initial state from prop only at mount: pass a function `useState(() => computeInitial(prop))` when computation is expensive
+- Functional updater when the new state depends on the old: `setCount(c => c + 1)` — never `setCount(count + 1)` inside async or batched contexts
+- Group related state into one object only when they always change together; otherwise split into multiple `useState` calls
+- Use `useReducer` once state transitions are conditional on the previous state or there are 3+ related values
+
+## `useRef` Patterns
+
+- DOM refs for imperative APIs (focus, scroll, third-party libs)
+- Mutable container that does not trigger re-render (timer ids, previous values, "is mounted" flags)
+- Never read or write `ref.current` during render — only inside effects or event handlers
+- `useImperativeHandle` only when exposing a child API to a parent ref — last-resort escape hatch
+
+## `useSyncExternalStore`
+
+Use this hook to subscribe to any external store (browser API, third-party state lib, custom event emitter). It is the supported way to make external state safe with concurrent rendering.
+
+```tsx
+const isOnline = useSyncExternalStore(
+  (cb) => {
+    window.addEventListener("online", cb);
+    window.addEventListener("offline", cb);
+    return () => {
+      window.removeEventListener("online", cb);
+      window.removeEventListener("offline", cb);
+    };
+  },
+  () => navigator.onLine,
+  () => true,
+);
+```
+
+## React 19 Additions
+
+- `use()` — unwrap promises and contexts inline; usable conditionally (only hook with that property)
+- `useFormStatus()` / `useFormState()` (or `useActionState`) — form submission state without prop drilling
+- `useOptimistic()` — optimistic UI updates while a server action is pending
+- `useTransition()` — mark non-urgent state updates so urgent ones stay responsive
+
+When the project targets React 19+, prefer these over hand-rolled equivalents.
+
+## Stale Closure Trap
+
+Async handlers and intervals capture the values from the render where they were created. Fix by:
+
+1. Using the functional updater form of `setState`
+2. Putting the changing value in the dep array of `useEffect` and rebuilding the handler
+3. Reading from a ref that is kept in sync
+
+## Lint Configuration
+
+Required rules:
+
+```json
+{
+  "rules": {
+    "react-hooks/rules-of-hooks": "error",
+    "react-hooks/exhaustive-deps": "warn"
+  }
+}
+```
+
+Treat `exhaustive-deps` warnings as errors in CI for new code.