@jmruthers/pace-core 0.6.6 → 0.6.8

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

@@ -1,348 +0,0 @@
-# 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

@@ -1,370 +0,0 @@
-# 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`
-