@jmruthers/pace-core 0.6.4 → 0.6.6

package/docs/standards/11-performance-optimization.md

@@ -0,0 +1,348 @@
+# Performance Optimization Guide
+
+**🤖 Cursor Rule**: See [11-performance-optimization.mdc](../../cursor-rules/11-performance-optimization.mdc) for AI-optimized directives that automatically enforce performance best practices.
+
+## Purpose
+
+This standard defines performance optimization patterns and best practices to ensure:
+- **Fast page loads** and responsive user interfaces
+- **Efficient database queries** with proper RLS optimization
+- **Optimized React rendering** with proper memoization
+- **Effective caching strategies** for server state
+- **Minimal bundle sizes** and code splitting
+
+## Principles
+
+1. **Measure before optimizing** - Profile and identify bottlenecks
+2. **Optimize critical paths first** - Focus on user-facing performance
+3. **Use appropriate caching** - Balance freshness with performance
+4. **Minimize re-renders** - Use React optimization techniques
+5. **Optimize database queries** - Use helper functions, avoid N+1 queries
+
+## React Performance
+
+### Memoization
+
+**Use `useMemo` for expensive computations:**
+
+```tsx
+// ✅ CORRECT - Memoize expensive computation
+const expensiveValue = useMemo(() => {
+  return computeExpensiveValue(data);
+}, [data]);
+
+// ❌ WRONG - Recomputes on every render
+const expensiveValue = computeExpensiveValue(data);
+```
+
+**Use `useCallback` for stable function references:**
+
+```tsx
+// ✅ CORRECT - Stable callback reference
+const handleClick = useCallback(() => {
+  doSomething(id);
+}, [id]);
+
+// ❌ WRONG - New function on every render
+const handleClick = () => {
+  doSomething(id);
+};
+```
+
+**Use `React.memo` for expensive components:**
+
+```tsx
+// ✅ CORRECT - Memoize component
+const ExpensiveComponent = React.memo(({ data }) => {
+  return <div>{/* expensive rendering */}</div>;
+});
+
+// ❌ WRONG - Re-renders unnecessarily
+function ExpensiveComponent({ data }) {
+  return <div>{/* expensive rendering */}</div>;
+}
+```
+
+### Avoiding Unnecessary Re-renders
+
+**Don't create new objects/arrays in render:**
+
+```tsx
+// ❌ WRONG - New object on every render
+function Component({ items }) {
+  const config = { items, enabled: true };
+  return <Child config={config} />;
+}
+
+// ✅ CORRECT - Memoize object
+function Component({ items }) {
+  const config = useMemo(() => ({ items, enabled: true }), [items]);
+  return <Child config={config} />;
+}
+```
+
+### Code Splitting
+
+**Lazy load heavy components:**
+
+```tsx
+// ✅ CORRECT - Lazy load
+import { lazy, Suspense } from 'react';
+const HeavyComponent = lazy(() => import('./HeavyComponent'));
+
+function App() {
+  return (
+    <Suspense fallback={<Loading />}>
+      <HeavyComponent />
+    </Suspense>
+  );
+}
+```
+
+## Database Performance
+
+### RLS Policy Optimization
+
+**MUST use helper functions (STABLE SECURITY DEFINER):**
+
+```sql
+-- ✅ CORRECT - Helper function (evaluated once)
+CREATE POLICY "rbac_select_users" ON users FOR SELECT USING (
+  check_user_organisation_access(organisation_id)
+);
+
+-- ❌ WRONG - Subquery (evaluated per row)
+CREATE POLICY "rbac_select_users" ON users FOR SELECT USING (
+  organisation_id IN (SELECT organisation_id FROM organisation_memberships WHERE user_id = auth.uid())
+);
+```
+
+**MUST avoid InitPlan nodes:**
+
+```sql
+-- ❌ WRONG - Causes InitPlan (severe performance degradation)
+CREATE POLICY "bad_policy" ON table_name FOR SELECT USING (
+  user_id = auth.uid()  -- Called for every row!
+);
+
+-- ✅ CORRECT - Helper function
+CREATE POLICY "good_policy" ON table_name FOR SELECT USING (
+  get_effective_user_id() = user_id  -- Evaluated once
+);
+```
+
+### Query Optimization
+
+**Use indexes for frequently queried columns:**
+
+```sql
+-- ✅ CORRECT - Index on frequently queried column
+CREATE INDEX idx_users_organisation_id ON users(organisation_id);
+CREATE INDEX idx_events_organisation_id_event_id ON events(organisation_id, event_id);
+```
+
+**Avoid N+1 queries:**
+
+```tsx
+// ❌ WRONG - N+1 queries
+const events = await fetchEvents();
+for (const event of events) {
+  const users = await fetchEventUsers(event.id); // N queries!
+}
+
+// ✅ CORRECT - Single query with join
+const eventsWithUsers = await fetchEventsWithUsers(); // 1 query
+```
+
+**Use RPC functions for complex queries:**
+
+```tsx
+// ✅ CORRECT - RPC for complex query
+const { data } = await supabase.rpc('data_events_list', { 
+  organisation_id: orgId 
+});
+
+// ❌ AVOID - Complex client-side query
+const { data } = await supabase
+  .from('events')
+  .select('*, users(*), organisations(*)')
+  .eq('organisation_id', orgId);
+```
+
+## Caching Strategies
+
+### TanStack Query Configuration
+
+**Configure appropriate cache times:**
+
+```tsx
+// ✅ CORRECT - Configure cache
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 5 * 60 * 1000,    // 5 minutes
+      cacheTime: 10 * 60 * 1000,   // 10 minutes
+      retry: 1,
+      refetchOnWindowFocus: false, // Prevent unnecessary refetches
+    },
+  },
+});
+```
+
+**Use query keys effectively:**
+
+```tsx
+// ✅ CORRECT - Specific query keys
+const { data } = useQuery({
+  queryKey: ['events', organisationId, eventId],
+  queryFn: () => fetchEvent(organisationId, eventId),
+});
+
+// ❌ WRONG - Too generic
+const { data } = useQuery({
+  queryKey: ['events'],
+  queryFn: () => fetchEvent(organisationId, eventId),
+});
+```
+
+### React Query Optimizations
+
+**Use `keepPreviousData` for pagination:**
+
+```tsx
+// ✅ CORRECT - Keep previous data during pagination
+const { data } = useQuery({
+  queryKey: ['events', page],
+  queryFn: () => fetchEvents(page),
+  keepPreviousData: true,
+});
+```
+
+**Use `select` to transform data efficiently:**
+
+```tsx
+// ✅ CORRECT - Transform in select (only runs when data changes)
+const { data: eventCount } = useQuery({
+  queryKey: ['events'],
+  queryFn: fetchEvents,
+  select: (data) => data.length,
+});
+```
+
+## Bundle Size Optimization
+
+### Tree Shaking
+
+**Use named imports:**
+
+```tsx
+// ✅ CORRECT - Tree-shakeable
+import { Button, Card } from '@jmruthers/pace-core';
+
+// ❌ WRONG - Imports entire library
+import * as PaceCore from '@jmruthers/pace-core';
+```
+
+### Dynamic Imports
+
+**Lazy load heavy dependencies:**
+
+```tsx
+// ✅ CORRECT - Dynamic import
+const HeavyLibrary = lazy(() => import('heavy-library'));
+
+// ❌ WRONG - Eager import
+import HeavyLibrary from 'heavy-library';
+```
+
+## Performance Monitoring
+
+### Measuring Performance
+
+**Use React DevTools Profiler:**
+
+1. Open React DevTools
+2. Go to Profiler tab
+3. Record a session
+4. Identify slow components
+5. Optimize based on findings
+
+**Use browser DevTools:**
+
+1. Open Performance tab
+2. Record page load
+3. Identify bottlenecks
+4. Optimize critical rendering path
+
+### Performance Metrics
+
+**Track these metrics:**
+
+- **Time to First Byte (TTFB)** - < 200ms
+- **First Contentful Paint (FCP)** - < 1.8s
+- **Largest Contentful Paint (LCP)** - < 2.5s
+- **Time to Interactive (TTI)** - < 3.8s
+- **Cumulative Layout Shift (CLS)** - < 0.1
+
+## Performance Checklist
+
+Before committing performance-sensitive code, verify:
+
+- [ ] Expensive computations memoized with `useMemo`
+- [ ] Callbacks stable with `useCallback`
+- [ ] Components memoized with `React.memo` when appropriate
+- [ ] No new objects/arrays created in render
+- [ ] Heavy components lazy loaded
+- [ ] RLS policies use helper functions (no subqueries)
+- [ ] Queries use indexes appropriately
+- [ ] No N+1 query patterns
+- [ ] TanStack Query configured with appropriate cache times
+- [ ] Bundle size optimized (tree shaking, code splitting)
+- [ ] Performance metrics measured and acceptable
+
+## Common Performance Pitfalls
+
+### ❌ Don't: Create New Objects in Render
+
+```tsx
+// ❌ WRONG
+function Component({ items }) {
+  return <Child config={{ items, enabled: true }} />; // New object every render
+}
+```
+
+### ❌ Don't: Use Inline Functions
+
+```tsx
+// ❌ WRONG
+<Button onClick={() => handleClick(id)}>Click</Button> // New function every render
+```
+
+### ❌ Don't: Over-Memoize
+
+```tsx
+// ❌ WRONG - Memoizing simple computation
+const simpleValue = useMemo(() => items.length, [items]); // Unnecessary
+```
+
+### ❌ Don't: Use Subqueries in RLS
+
+```sql
+-- ❌ WRONG - N+1 performance issue
+CREATE POLICY "bad" ON table FOR SELECT USING (
+  organisation_id IN (SELECT ... FROM ... WHERE user_id = auth.uid())
+);
+```
+
+## Related Documentation
+
+- [RLS Standard](./09-rbac-compliance.md) - RLS performance requirements
+- [Code Quality Standard](./06-code-quality.md) - React performance patterns
+- [Tech Stack Standard](./07-tech-stack-compliance.md) - TanStack Query configuration
+
+---
+
+**Last Updated:** 2025-01-28  
+**Version:** 1.0.0  
+**Applies to:** All pace-core and consuming apps
+

package/docs/standards/12-ci-cd-integration.md

@@ -0,0 +1,370 @@
+# CI/CD Integration Guide
+
+**🤖 Cursor Rule**: See [12-ci-cd-integration.mdc](../../cursor-rules/12-ci-cd-integration.mdc) for AI-optimized directives that automatically enforce CI/CD best practices.
+
+## Purpose
+
+This standard defines CI/CD integration patterns and best practices to ensure:
+- **Automated quality checks** on every commit
+- **Consistent deployment processes** across environments
+- **Proper testing** before deployment
+- **Security scanning** and compliance checks
+- **Efficient build and deployment** pipelines
+
+## Principles
+
+1. **Automate everything** - Manual steps are error-prone
+2. **Fail fast** - Catch issues early in the pipeline
+3. **Test before deploy** - Never deploy untested code
+4. **Security first** - Scan for vulnerabilities
+5. **Consistent environments** - Dev, staging, production parity
+
+## CI/CD Pipeline Structure
+
+### Standard Pipeline Stages
+
+```
+1. Lint & Format Check
+2. Type Check
+3. Unit Tests
+4. Integration Tests
+5. Build
+6. Security Scan
+7. Deploy (staging/production)
+```
+
+## GitHub Actions Example
+
+### Basic Workflow
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  quality-checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Lint
+        run: npm run lint
+      
+      - name: Type check
+        run: npm run type-check
+      
+      - name: Format check
+        run: npm run format:check
+      
+      - name: Run tests
+        run: npm run test
+      
+      - name: Build
+        run: npm run build
+      
+      - name: Security scan
+        run: npm audit --audit-level=moderate
+```
+
+### Advanced Workflow with Deployment
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run test
+      - run: npm run build
+
+  deploy-staging:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: staging
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npm run build
+      - name: Deploy to Staging
+        run: |
+          # Your deployment script
+          echo "Deploying to staging..."
+
+  deploy-production:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: production
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npm run build
+      - name: Deploy to Production
+        run: |
+          # Your deployment script
+          echo "Deploying to production..."
+```
+
+## Required CI Checks
+
+### MUST: Run These Checks
+
+**Every CI pipeline MUST include:**
+
+1. **Linting** - ESLint with pace-core rules
+   ```yaml
+   - name: Lint
+     run: npm run lint
+   ```
+
+2. **Type Checking** - TypeScript compilation
+   ```yaml
+   - name: Type check
+     run: npx tsc --noEmit
+   ```
+
+3. **Testing** - Unit and integration tests
+   ```yaml
+   - name: Run tests
+     run: npm run test
+   ```
+
+4. **Build** - Verify build succeeds
+   ```yaml
+   - name: Build
+     run: npm run build
+   ```
+
+
+### SHOULD: Run These Checks
+
+**Recommended additional checks:**
+
+1. **Format Check** - Prettier or similar
+   ```yaml
+   - name: Format check
+     run: npm run format:check
+   ```
+
+2. **Security Scan** - npm audit or Snyk
+   ```yaml
+   - name: Security scan
+     run: npm audit --audit-level=moderate
+   ```
+
+3. **Coverage Check** - Test coverage thresholds
+   ```yaml
+   - name: Coverage check
+     run: npm run test:coverage
+   ```
+
+## Package.json Scripts
+
+### Required Scripts
+
+**MUST have these scripts in `package.json`:**
+
+```json
+{
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "build": "vite build",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  }
+}
+```
+
+## Environment Variables
+
+### CI/CD Secrets
+
+**Store sensitive values as secrets:**
+
+```yaml
+# .github/workflows/deploy.yml
+env:
+  SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
+  SUPABASE_ANON_KEY: ${{ secrets.SUPABASE_ANON_KEY }}
+  VITE_SUPABASE_URL: ${{ secrets.VITE_SUPABASE_URL }}
+  VITE_SUPABASE_ANON_KEY: ${{ secrets.VITE_SUPABASE_ANON_KEY }}
+```
+
+**Never commit secrets to repository:**
+- Use GitHub Secrets
+- Use environment-specific config files
+- Use `.env.example` for documentation
+
+## Database Migrations in CI/CD
+
+### Migration Strategy
+
+**For Supabase migrations:**
+
+```yaml
+- name: Run migrations
+  run: |
+    npx supabase db push
+    # Or use Supabase CLI
+    supabase migration up
+```
+
+**Best Practices:**
+- Run migrations in staging first
+- Test migrations in CI
+- Never run destructive migrations automatically
+- Use migration review process
+
+## Deployment Strategies
+
+### Staging Deployment
+
+**Deploy to staging on every merge to `develop`:**
+
+```yaml
+deploy-staging:
+  if: github.ref == 'refs/heads/develop'
+  environment: staging
+  steps:
+    - name: Deploy to Staging
+      run: |
+        # Deploy to staging environment
+```
+
+### Production Deployment
+
+**Deploy to production only from `main` branch:**
+
+```yaml
+deploy-production:
+  if: github.ref == 'refs/heads/main'
+  environment: production
+  steps:
+    - name: Deploy to Production
+      run: |
+        # Deploy to production environment
+```
+
+### Manual Deployment
+
+**Allow manual deployment via workflow_dispatch:**
+
+```yaml
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: 'Environment to deploy to'
+        required: true
+        type: choice
+        options:
+          - staging
+          - production
+```
+
+## CI/CD Checklist
+
+Before setting up CI/CD, verify:
+
+- [ ] Lint check configured
+- [ ] Type check configured
+- [ ] Tests run in CI
+- [ ] Build succeeds in CI
+- [ ] Security scan configured
+- [ ] Environment variables set as secrets
+- [ ] Staging deployment configured
+- [ ] Production deployment configured
+- [ ] Migration strategy defined
+- [ ] Rollback plan documented
+
+## Common CI/CD Issues
+
+### Issue: Tests Fail in CI but Pass Locally
+
+**Causes:**
+- Environment differences
+- Missing environment variables
+- Timezone issues
+- File path differences
+
+**Solutions:**
+- Use same Node.js version
+- Set all required environment variables
+- Use consistent timezone (UTC)
+- Use absolute paths or path aliases
+
+### Issue: Build Fails in CI
+
+**Causes:**
+- Missing dependencies
+- Different Node.js version
+- Platform-specific code
+
+**Solutions:**
+- Use `npm ci` (not `npm install`)
+- Pin Node.js version
+- Test on same platform as CI
+
+### Issue: Slow CI Pipeline
+
+**Causes:**
+- Running unnecessary checks
+- Not caching dependencies
+- Sequential jobs
+
+**Solutions:**
+- Cache node_modules
+- Run jobs in parallel
+- Only run necessary checks per branch
+
+## Related Documentation
+
+- [Testing Standard](./04-testing-standards.md) - Test configuration
+- [Code Quality Standard](./06-code-quality.md) - Linting and formatting
+- [pace-core Compliance](./00-pace-core-compliance.md) - Compliance checks
+
+---
+
+**Last Updated:** 2025-01-28  
+**Version:** 1.0.0  
+**Applies to:** All consuming apps using `@jmruthers/pace-core`
+