@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/testing-vitest.md

@@ -0,0 +1,232 @@
+---
+name: testing-vitest
+description: Vitest testing patterns including describe/it/expect, mocking with vi.*, snapshot testing, and coverage configuration.
+---
+
+# Vitest Testing Patterns
+
+## When to Use
+Use Vitest when writing unit and integration tests for TypeScript or JavaScript projects. Vitest is the preferred test runner for Vite-based projects and any modern TS codebase that benefits from native ESM support and fast HMR-driven test execution. Apply these patterns whenever you need to test pure functions, modules with dependencies, async code, or React components.
+
+## How It Works
+
+### Basic Test Structure
+
+Every test file follows the describe/it/expect pattern:
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { calculateDiscount } from '../src/pricing';
+
+describe('calculateDiscount', () => {
+  let basePrice: number;
+
+  beforeEach(() => {
+    basePrice = 100;
+  });
+
+  it('applies percentage discount correctly', () => {
+    const result = calculateDiscount(basePrice, { type: 'percent', value: 20 });
+    expect(result).toBe(80);
+  });
+
+  it('applies fixed discount correctly', () => {
+    const result = calculateDiscount(basePrice, { type: 'fixed', value: 15 });
+    expect(result).toBe(85);
+  });
+
+  it('never returns a negative price', () => {
+    const result = calculateDiscount(basePrice, { type: 'fixed', value: 200 });
+    expect(result).toBe(0);
+  });
+
+  it('throws on invalid discount type', () => {
+    expect(() => calculateDiscount(basePrice, { type: 'bogus' as any, value: 10 }))
+      .toThrow('Unknown discount type: bogus');
+  });
+});
+```
+
+### Mocking with vi.*
+
+Replace dependencies with controlled implementations:
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { fetchUserProfile } from '../src/user-service';
+
+// Mock an entire module
+vi.mock('../src/api-client', () => ({
+  apiClient: {
+    get: vi.fn(),
+  },
+}));
+
+import { apiClient } from '../src/api-client';
+
+describe('fetchUserProfile', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns parsed user data', async () => {
+    vi.mocked(apiClient.get).mockResolvedValueOnce({
+      data: { id: '1', name: 'Alice', email: 'alice@example.com' },
+    });
+
+    const profile = await fetchUserProfile('1');
+
+    expect(apiClient.get).toHaveBeenCalledWith('/users/1');
+    expect(profile).toEqual({ id: '1', name: 'Alice', email: 'alice@example.com' });
+  });
+
+  it('throws on network error', async () => {
+    vi.mocked(apiClient.get).mockRejectedValueOnce(new Error('Network timeout'));
+
+    await expect(fetchUserProfile('1')).rejects.toThrow('Network timeout');
+  });
+});
+```
+
+### Spying on Methods
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+
+describe('Logger', () => {
+  it('tracks console.warn calls', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    console.warn('deprecation notice');
+
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(warnSpy).toHaveBeenCalledWith('deprecation notice');
+
+    warnSpy.mockRestore();
+  });
+});
+```
+
+### Timer Mocking
+
+```typescript
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { debounce } from '../src/utils';
+
+describe('debounce', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('delays execution by the specified ms', () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 300);
+
+    debounced();
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(299);
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(1);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+});
+```
+
+### Snapshot Testing
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { generateConfig } from '../src/config-builder';
+
+describe('generateConfig', () => {
+  it('matches snapshot for production env', () => {
+    const config = generateConfig({ env: 'production', region: 'us-east-1' });
+    expect(config).toMatchInlineSnapshot(`
+      {
+        "cache": true,
+        "debug": false,
+        "logLevel": "error",
+        "region": "us-east-1",
+      }
+    `);
+  });
+
+  it('matches file snapshot for full config', () => {
+    const config = generateConfig({ env: 'staging', region: 'eu-west-1' });
+    expect(config).toMatchSnapshot();
+  });
+});
+```
+
+### Coverage Configuration
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['**/*.test.ts', '**/*.spec.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'html', 'lcov'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.d.ts', 'src/**/__tests__/**', 'src/**/index.ts'],
+      thresholds: {
+        branches: 80,
+        functions: 80,
+        lines: 80,
+        statements: 80,
+      },
+    },
+  },
+});
+```
+
+### Parameterized Tests
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { slugify } from '../src/string-utils';
+
+describe('slugify', () => {
+  it.each([
+    ['Hello World', 'hello-world'],
+    ['  Leading spaces  ', 'leading-spaces'],
+    ['Special Ch@r$!', 'special-chr'],
+    ['already-slugged', 'already-slugged'],
+    ['UPPERCASE', 'uppercase'],
+  ])('slugify(%j) => %j', (input, expected) => {
+    expect(slugify(input)).toBe(expected);
+  });
+});
+```
+
+## Examples
+
+| Pattern | Use Case |
+|---------|----------|
+| `vi.fn()` | Create a standalone mock function for callbacks |
+| `vi.mock('module')` | Replace an entire module import |
+| `vi.spyOn(obj, 'method')` | Watch calls without replacing implementation |
+| `vi.useFakeTimers()` | Control setTimeout/setInterval/Date |
+| `vi.mocked(fn)` | Get typed mock from an auto-mocked function |
+| `toMatchInlineSnapshot()` | Pin output directly in the test file |
+| `it.each([...])` | Run the same assertion with different inputs |
+
+## Checklist
+- [ ] Every test file imports from `vitest`, not from `jest` or `@jest/globals`
+- [ ] `vi.clearAllMocks()` is called in `beforeEach` when mocks are shared across tests
+- [ ] Fake timers are restored in `afterEach` with `vi.useRealTimers()`
+- [ ] Spies are restored with `mockRestore()` to prevent leakage between tests
+- [ ] Coverage thresholds are set in `vitest.config.ts` and enforced in CI
+- [ ] Async tests use `await expect(...).resolves` or `.rejects` instead of try/catch
+- [ ] Snapshot files are committed and reviewed in PRs for unexpected changes

package/assets/skills/typescript-strict.md

@@ -0,0 +1,159 @@
+---
+name: typescript-strict
+description: Enforce strict TypeScript patterns to catch bugs at compile time instead of runtime.
+---
+
+# Strict TypeScript Patterns
+
+## When to Use
+
+Apply these patterns whenever you write or review TypeScript code. Strict typing
+eliminates entire categories of runtime errors — null reference crashes, missing
+case handling, accidental type coercion, and silent data corruption. Use this
+skill from day one of a project, not as a retrofit.
+
+## How It Works
+
+### 1. Ban `any` — Use `unknown` Instead
+
+`any` disables the type checker. `unknown` forces you to narrow before use.
+
+```typescript
+// Bad — silent runtime crash
+function parse(input: any) {
+  return input.data.items; // no error, but blows up if input is null
+}
+
+// Good — compiler forces narrowing
+function parse(input: unknown): Item[] {
+  if (typeof input === 'object' && input !== null && 'data' in input) {
+    const data = (input as { data: { items: Item[] } }).data;
+    return data.items;
+  }
+  throw new ParseError('Invalid input shape');
+}
+```
+
+Enable `"noImplicitAny": true` in tsconfig. Lint with `@typescript-eslint/no-explicit-any`.
+
+### 2. Discriminated Unions for State Modeling
+
+Model mutually exclusive states with a literal discriminant field.
+
+```typescript
+type AsyncState<T> =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: T }
+  | { status: 'error'; error: Error };
+
+function render(state: AsyncState<User>) {
+  switch (state.status) {
+    case 'idle':    return <Placeholder />;
+    case 'loading': return <Spinner />;
+    case 'success': return <Profile user={state.data} />; // data is narrowed
+    case 'error':   return <Alert message={state.error.message} />;
+  }
+}
+```
+
+### 3. Exhaustive Switch Checks
+
+Use `never` to catch unhandled union members at compile time.
+
+```typescript
+function assertNever(x: never): never {
+  throw new Error(`Unexpected value: ${JSON.stringify(x)}`);
+}
+
+function handleEvent(event: AppEvent) {
+  switch (event.type) {
+    case 'click':   return onClick(event);
+    case 'keydown': return onKeydown(event);
+    default:        return assertNever(event); // compile error if a case is missing
+  }
+}
+```
+
+### 4. Branded Types for Domain Safety
+
+Prevent mixing structurally identical but semantically different values.
+
+```typescript
+type UserId = string & { readonly __brand: 'UserId' };
+type OrderId = string & { readonly __brand: 'OrderId' };
+
+function createUserId(raw: string): UserId { return raw as UserId; }
+function createOrderId(raw: string): OrderId { return raw as OrderId; }
+
+function getUser(id: UserId): Promise<User> { /* ... */ }
+
+const orderId = createOrderId('abc-123');
+getUser(orderId); // Compile error — OrderId is not assignable to UserId
+```
+
+### 5. Const Assertions and Readonly
+
+Lock down object shapes and array contents.
+
+```typescript
+const ROLES = ['admin', 'editor', 'viewer'] as const;
+type Role = (typeof ROLES)[number]; // 'admin' | 'editor' | 'viewer'
+
+interface Config {
+  readonly apiUrl: string;
+  readonly retries: number;
+}
+```
+
+### 6. Template Literal Types for String Patterns
+
+Constrain strings to known patterns without regex at runtime.
+
+```typescript
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+type Route = `/${string}`;
+type Endpoint = `${HttpMethod} ${Route}`;
+
+const endpoint: Endpoint = 'GET /users'; // valid
+const bad: Endpoint = 'FETCH /users';    // compile error
+```
+
+### 7. Strict tsconfig Settings
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": true,
+    "noPropertyAccessFromIndexSignature": true
+  }
+}
+```
+
+`noUncheckedIndexedAccess` is the most impactful — it makes `array[0]` return
+`T | undefined` instead of `T`, catching out-of-bounds access.
+
+## Examples
+
+| Pattern | Catches | Cost |
+|---------|---------|------|
+| Ban `any` | Type coercion bugs | Slightly more verbose parsers |
+| Discriminated unions | Impossible state combinations | ~2 extra lines per type |
+| Exhaustive checks | Unhandled cases after adding variants | One utility function |
+| Branded types | ID mixups across domain boundaries | Factory function per type |
+| `noUncheckedIndexedAccess` | Array/object out-of-bounds | More `?.` and null checks |
+
+## Checklist
+
+- [ ] `"strict": true` is enabled in tsconfig with no per-file overrides
+- [ ] `noUncheckedIndexedAccess` is enabled
+- [ ] Zero `any` in application code (vendored types excluded)
+- [ ] All union switches use exhaustive `assertNever` in the default branch
+- [ ] Domain IDs use branded types, not raw strings
+- [ ] Object configs use `as const` or `Readonly<>` where mutation is unintended
+- [ ] ESLint rule `@typescript-eslint/no-explicit-any` is set to error
+- [ ] CI fails on type errors — `tsc --noEmit` is in the pipeline