@ngxtm/devkit 3.4.0 → 3.5.0

package/rules/react/security/references/REFERENCE.md

@@ -0,0 +1,170 @@
+# React Security Reference
+
+CSP configuration and advanced security patterns.
+
+## References
+
+- [**Content Security Policy**](csp.md) - CSP headers configuration.
+- [**Auth Patterns**](auth-patterns.md) - Secure authentication flows.
+
+## Content Security Policy
+
+```jsx
+// Next.js middleware or server config
+const cspHeader = `
+  default-src 'self';
+  script-src 'self' 'unsafe-inline' 'unsafe-eval';
+  style-src 'self' 'unsafe-inline';
+  img-src 'self' blob: data: https:;
+  font-src 'self';
+  object-src 'none';
+  base-uri 'self';
+  form-action 'self';
+  frame-ancestors 'none';
+  upgrade-insecure-requests;
+`;
+
+// Vite plugin for CSP
+import { defineConfig } from 'vite';
+import htmlPlugin from 'vite-plugin-html';
+
+export default defineConfig({
+  plugins: [
+    htmlPlugin({
+      inject: {
+        data: {
+          csp: cspHeader.replace(/\s+/g, ' ').trim(),
+        },
+      },
+    }),
+  ],
+});
+```
+
+## OAuth2 / JWT Authentication Flow
+
+```jsx
+import { createContext, useContext, useState, useEffect } from 'react';
+
+const AuthContext = createContext(null);
+
+export function AuthProvider({ children }) {
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    // Check if user is already authenticated
+    checkAuth();
+  }, []);
+
+  const checkAuth = async () => {
+    try {
+      // Token is in httpOnly cookie, automatically sent
+      const response = await fetch('/api/auth/me', {
+        credentials: 'include',
+      });
+      
+      if (response.ok) {
+        const userData = await response.json();
+        setUser(userData);
+      }
+    } catch (error) {
+      console.error('Auth check failed:', error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const login = async (credentials) => {
+    const response = await fetch('/api/auth/login', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      credentials: 'include',
+      body: JSON.stringify(credentials),
+    });
+
+    if (!response.ok) {
+      throw new Error('Login failed');
+    }
+
+    const userData = await response.json();
+    setUser(userData);
+  };
+
+  const logout = async () => {
+    await fetch('/api/auth/logout', {
+      method: 'POST',
+      credentials: 'include',
+    });
+    setUser(null);
+  };
+
+  return (
+    <AuthContext.Provider value={{ user, loading, login, logout }}>
+      {children}
+    </AuthContext.Provider>
+  );
+}
+
+export function useAuth() {
+  const context = useContext(AuthContext);
+  if (!context) {
+    throw new Error('useAuth must be used within AuthProvider');
+  }
+  return context;
+}
+```
+
+## CSRF Protection
+
+```jsx
+// Get CSRF token from cookie or meta tag
+function getCsrfToken() {
+  return document.querySelector('meta[name="csrf-token"]')?.content;
+}
+
+// Include in requests
+async function securePost(url, data) {
+  const csrfToken = getCsrfToken();
+  
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-CSRF-Token': csrfToken,
+    },
+    credentials: 'include',
+    body: JSON.stringify(data),
+  });
+
+  return response;
+}
+```
+
+## Rate Limiting on Client
+
+```jsx
+// Simple rate limiter for API calls
+function createRateLimiter(maxCalls, timeWindow) {
+  const calls = [];
+
+  return function rateLimitedFetch(url, options) {
+    const now = Date.now();
+    
+    // Remove old calls outside time window
+    while (calls.length > 0 && calls[0] < now - timeWindow) {
+      calls.shift();
+    }
+
+    if (calls.length >= maxCalls) {
+      throw new Error('Rate limit exceeded');
+    }
+
+    calls.push(now);
+    return fetch(url, options);
+  };
+}
+
+// Usage: max 10 calls per 60 seconds
+const rateLimitedFetch = createRateLimiter(10, 60000);
+```

package/rules/react/state-management/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: React State Management
+description: Standards for managing local, global, and server state.
+metadata:
+  labels: [react, state, redux, zustand, context]
+  triggers:
+    files: ['**/*.tsx', '**/*.jsx']
+    keywords: [state, useReducer, context, store, props]
+---
+
+# React State Management
+
+## **Priority: P0 (CRITICAL)**
+
+Choosing the right tool for state scope.
+
+## Implementation Guidelines
+
+- **Local**: `useState`. `useReducer` if complex (state machine).
+- **Derived**: `const fullName = first + last`. No state sync.
+- **Context**: DI, Theming, Auth. Not for high-freq data.
+- **Global**: Zustand/Redux for app-wide complex flow.
+- **Server Cache**: Use `React.cache` (RSC) to dedupe requests per render.
+- **Server State**: React Query / SWR / Apollo. Cache != UI State.
+- **URL**: Store filter/sort params in URL (Source of Truth).
+- **Immutability**: Never mutate. Use spread or Immer.
+
+## Anti-Patterns
+
+- **No Prop Drilling > 2**: Use Context/Composition.
+- **No Mirroring Refs**: Don't copy props to state.
+- **No Multi-Source**: Single Source of Truth.
+- **No Context Abuse**: Context causes full-tree re-render.
+
+## Code
+
+```tsx
+// Derived State (Efficient)
+function List({ items, filter }) {
+  // Correct: Calculated on fly
+  const visible = items.filter((i) => i.includes(filter));
+  return (
+    <ul>
+      {visible.map((i) => (
+        <li key={i}>{i}</li>
+      ))}
+    </ul>
+  );
+}
+
+// Zustand (Global)
+const useStore = create((set) => ({
+  count: 0,
+  inc: () => set((s) => ({ count: s.count + 1 })),
+}));
+```

package/rules/react/state-management/references/REFERENCE.md

@@ -0,0 +1,137 @@
+# React State Management Reference
+
+Advanced state management with Zustand, Redux Toolkit, and TanStack Query.
+
+## References
+
+- [**Zustand**](zustand.md) - Lightweight state management.
+- [**Redux Toolkit**](redux-toolkit.md) - Redux best practices.
+- [**TanStack Query**](tanstack-query.md) - Server state management.
+
+## Zustand Store
+
+```jsx
+import { create } from 'zustand';
+
+// Simple store
+export const useStore = create((set) => ({
+  count: 0,
+  increment: () => set((state) => ({ count: state.count + 1 })),
+  decrement: () => set((state) => ({ count: state.count - 1 })),
+  reset: () => set({ count: 0 }),
+}));
+
+// Advanced store with middleware
+import { devtools, persist } from 'zustand/middleware';
+
+export const useAuthStore = create(
+  devtools(
+    persist(
+      (set) => ({
+        user: null,
+        token: null,
+        login: (user, token) => set({ user, token }),
+        logout: () => set({ user: null, token: null }),
+      }),
+      { name: 'auth-storage' }
+    )
+  )
+);
+
+// Usage
+function Component() {
+  const count = useStore((state) => state.count);
+  const increment = useStore((state) => state.increment);
+  
+  return <button onClick={increment}>Count: {count}</button>;
+}
+```
+
+## Redux Toolkit
+
+```jsx
+import { createSlice, configureStore } from '@reduxjs/toolkit';
+
+// Slice
+const counterSlice = createSlice({
+  name: 'counter',
+  initialState: { value: 0 },
+  reducers: {
+    increment: (state) => {
+      state.value += 1; // Immer allows mutation
+    },
+    decrement: (state) => {
+      state.value -= 1;
+    },
+    incrementByAmount: (state, action) => {
+      state.value += action.payload;
+    },
+  },
+});
+
+export const { increment, decrement, incrementByAmount } = counterSlice.actions;
+
+// Store
+export const store = configureStore({
+  reducer: {
+    counter: counterSlice.reducer,
+  },
+});
+
+// Usage with hooks
+import { useSelector, useDispatch } from 'react-redux';
+
+function Counter() {
+  const count = useSelector((state) => state.counter.value);
+  const dispatch = useDispatch();
+  
+  return (
+    <div>
+      <button onClick={() => dispatch(decrement())}>-</button>
+      <span>{count}</span>
+      <button onClick={() => dispatch(increment())}>+</button>
+    </div>
+  );
+}
+```
+
+## TanStack Query (React Query)
+
+```jsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+
+// Fetch data
+function UserProfile({ userId }) {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => fetch(`/api/users/${userId}`).then(r => r.json()),
+    staleTime: 5 * 60 * 1000, // 5 minutes
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return <div>{data.name}</div>;
+}
+
+// Mutations
+function CreateUser() {
+  const queryClient = useQueryClient();
+  
+  const mutation = useMutation({
+    mutationFn: (newUser) => fetch('/api/users', {
+      method: 'POST',
+      body: JSON.stringify(newUser),
+    }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] });
+    },
+  });
+
+  return (
+    <button onClick={() => mutation.mutate({ name: 'John' })}>
+      Create User
+    </button>
+  );
+}
+```

package/rules/react/testing/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: React Testing
+description: Testing strategies with RTL and Jest/Vitest.
+metadata:
+  labels: [react, testing, jest, vitest]
+  triggers:
+    files: ['**/*.test.tsx', '**/*.spec.tsx']
+    keywords: [render, screen, userEvent, expect]
+---
+
+# React Testing
+
+## **Priority: P2 (MAINTENANCE)**
+
+Reliable tests focusing on user behavior.
+
+## Implementation Guidelines
+
+- **Tooling**: React Testing Library + Vitest.
+- **Philosophy**: Test behavior, not implementation (State/Internal vars).
+- **Queries**: `getByRole` > `getByText` > `getByTestId`.
+- **Events**: Use `userEvent` (async) over `fireEvent`.
+- **Async**: `await screen.findBy*` for async updates.
+- **Mocks**: MSW for network. Mock heavy 3rd-party libs.
+- **Accessibility**: Testing Lib implicitly tests a11y roles.
+
+## Anti-Patterns
+
+- **No Shallow Rendering**: Render full tree.
+- **No Testing Implementation Details**: Don't check `component.state`.
+- **No Wait**: Use `findBy`, avoid `waitFor` if possible.
+
+## Code
+
+```tsx
+test('submits form', async () => {
+  const user = userEvent.setup();
+  render(<LoginForm />);
+
+  await user.type(screen.getByLabelText(/email/i), 'test@test.com');
+  await user.click(screen.getByRole('button', { name: /login/i }));
+
+  expect(await screen.findByText(/welcome/i)).toBeInTheDocument();
+});
+```

package/rules/react/testing/references/REFERENCE.md

@@ -0,0 +1,149 @@
+# React Testing Reference
+
+Advanced testing patterns and integration testing.
+
+## References
+
+- [**Mocking Patterns**](mocking.md) - API, module, and component mocking.
+- [**Integration Tests**](integration-tests.md) - Testing component interactions.
+
+## Mocking API Calls
+
+```jsx
+// Using MSW (Mock Service Worker)
+import { rest } from 'msw';
+import { setupServer } from 'msw/node';
+
+const server = setupServer(
+  rest.get('/api/users/:id', (req, res, ctx) => {
+    const { id } = req.params;
+    return res(
+      ctx.json({ id, name: 'John Doe', email: 'john@example.com' })
+    );
+  })
+);
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+test('fetches and displays user', async () => {
+  render(<UserProfile userId="1" />);
+  
+  expect(await screen.findByText('John Doe')).toBeInTheDocument();
+});
+
+// Override handler for error case
+test('handles fetch error', async () => {
+  server.use(
+    rest.get('/api/users/:id', (req, res, ctx) => {
+      return res(ctx.status(500));
+    })
+  );
+  
+  render(<UserProfile userId="1" />);
+  
+  expect(await screen.findByText(/error/i)).toBeInTheDocument();
+});
+```
+
+## Testing Context
+
+```jsx
+import { render, screen } from '@testing-library/react';
+import { AuthProvider, useAuth } from './AuthContext';
+
+function TestComponent() {
+  const { user } = useAuth();
+  return <div>{user ? user.name : 'Not logged in'}</div>;
+}
+
+test('provides auth context', () => {
+  const mockUser = { id: '1', name: 'John' };
+  
+  render(
+    <AuthProvider initialUser={mockUser}>
+      <TestComponent />
+    </AuthProvider>
+  );
+  
+  expect(screen.getByText('John')).toBeInTheDocument();
+});
+```
+
+## Testing Forms
+
+```jsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { LoginForm } from './LoginForm';
+
+test('submits form with credentials', async () => {
+  const onSubmit = jest.fn();
+  const user = userEvent.setup();
+  
+  render(<LoginForm onSubmit={onSubmit} />);
+  
+  await user.type(screen.getByLabelText(/email/i), 'john@example.com');
+  await user.type(screen.getByLabelText(/password/i), 'password123');
+  await user.click(screen.getByRole('button', { name: /login/i }));
+  
+  expect(onSubmit).toHaveBeenCalledWith({
+    email: 'john@example.com',
+    password: 'password123',
+  });
+});
+
+test('shows validation errors', async () => {
+  const user = userEvent.setup();
+  
+  render(<LoginForm />);
+  
+  await user.click(screen.getByRole('button', { name: /login/i }));
+  
+  expect(await screen.findByText(/email is required/i)).toBeInTheDocument();
+});
+```
+
+## Testing with React Router
+
+```jsx
+import { render, screen } from '@testing-library/react';
+import { MemoryRouter, Routes, Route } from 'react-router-dom';
+import { Dashboard } from './Dashboard';
+
+test('renders dashboard at /dashboard', () => {
+  render(
+    <MemoryRouter initialEntries={['/dashboard']}>
+      <Routes>
+        <Route path="/dashboard" element={<Dashboard />} />
+      </Routes>
+    </MemoryRouter>
+  );
+  
+  expect(screen.getByText(/dashboard/i)).toBeInTheDocument();
+});
+```
+
+## Component Integration Tests
+
+```jsx
+test('user can complete full workflow', async () => {
+  const user = userEvent.setup();
+  
+  render(<App />);
+  
+  // Navigate to form
+  await user.click(screen.getByRole('link', { name: /create user/i }));
+  
+  // Fill form
+  await user.type(screen.getByLabelText(/name/i), 'Jane Doe');
+  await user.type(screen.getByLabelText(/email/i), 'jane@example.com');
+  
+  // Submit
+  await user.click(screen.getByRole('button', { name: /submit/i }));
+  
+  // Verify success
+  expect(await screen.findByText(/user created/i)).toBeInTheDocument();
+});
+```

package/rules/react/tooling/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: React Tooling
+description: Debugging, build analysis, and ecosystem tools.
+metadata:
+  labels: [react, tooling, debug, performance]
+  triggers:
+    files: ['package.json']
+    keywords: [devtool, bundle, strict mode, profile]
+---
+
+# React Tooling
+
+## **Priority: P2 (OPTIONAL)**
+
+Tools for analysis and debugging.
+
+## Implementation Guidelines
+
+- **DevTools**: Use "Highlight Updates" to spot re-renders.
+- **Debugger**: `useDebugValue` for custom hooks.
+- **Performance**: `why-did-you-render` to catch wasted renders.
+- **Bundle**: `source-map-explorer` or `bundle-visualizer`.
+- **Linting**: `eslint-plugin-react-hooks` (Errors) + `react-refresh`.
+- **Strict Mode**: Enable for double-invoke checks (effects/reducers).
+
+## Code
+
+```tsx
+// Debugging Hooks
+useDebugValue(isOnline ? 'Online' : 'Offline');
+
+// why-did-you-render
+if (process.env.NODE_ENV === 'development') {
+  const whyDidYouRender = require('@welldone-software/why-did-you-render');
+  whyDidYouRender(React, {
+    trackAllPureComponents: true,
+  });
+}
+```

package/rules/react/typescript/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: React TypeScript
+description: TypeScript patterns specific to React components and hooks.
+metadata:
+  labels: [react, typescript, types]
+  triggers:
+    files: ['**/*.tsx']
+    keywords: [ReactNode, FC, PropsWithChildren, ComponentProps]
+---
+
+# React TypeScript
+
+## **Priority: P1 (OPERATIONAL)**
+
+Type-safe React patterns.
+
+## Implementation Guidelines
+
+- **Components**: Return `JSX.Element`. Props interface over `React.FC`.
+- **Children**: Use `ReactNode` or `PropsWithChildren<T>`.
+- **Events**: `React.ChangeEvent<HTMLInputElement>`.
+- **Hooks**: `useRef<HTMLDivElement>(null)`. `useState<User | null>(null)`.
+- **Props**: Use `ComponentProps<'button'>` to mirror native els.
+- **Generics**: `<T,>(props: ListProps<T>)`.
+- **Polymorphism**: `as` prop patterns.
+
+## Anti-Patterns
+
+- **No `any`**: Use `unknown`.
+- **No `React.FC`**: Implicit children is deprecated/bad practice.
+- **No `Function`**: Use `(args: T) => void`.
+
+## Code
+
+```tsx
+// Modern Props
+type ButtonProps = ComponentProps<'button'> & {
+  variant?: 'primary' | 'secondary';
+};
+
+// Generic Component
+type ListProps<T> = {
+  items: T[];
+  render: (item: T) => ReactNode;
+};
+
+function List<T>({ items, render }: ListProps<T>) {
+  return <ul>{items.map(render)}</ul>;
+}
+
+// Hook Ref
+const inputRef = useRef<HTMLInputElement>(null);
+```