🚀 Advanced Retirement Planner v7.3.6 - Development Guide

Overview

This guide provides comprehensive development standards and workflows for the Advanced Retirement Planner v7.3.6. It covers component development, testing requirements, deployment processes, and best practices learned from production hotfixes and quality improvements.

🎯 Development Philosophy

Code Quality First

100% Test Pass Rate: All 374 tests must pass before deployment
Runtime Error Prevention: Component validation prevents production crashes
Security by Design: Input validation, XSS prevention, secret scanning
Performance Optimized: Parallel loading, caching, minimal bundle size

Development Principles

Test-Driven Development: Write tests as you develop features
Component Safety: Validate component rendering before deployment
Incremental Updates: Small, testable changes over large refactors
Documentation First: Update docs alongside code changes

🏗️ Development Environment Setup

Prerequisites

Node.js >= 18.x
npm >= 8.x
Git with proper configuration

Local Development Setup

# Clone repository
git clone https://github.com/ypollak2/advanced-retirement-planner.git
cd advanced-retirement-planner

# Install dependencies
npm install

# Run development server
npm run dev

# Run tests (required before any changes)
npm test

# Validate components (new requirement)
npm run validate:components

Development Scripts

# Core Development
npm run dev                    # Start development server
npm run build                  # Build for production
npm run preview                # Preview production build

# Testing (CRITICAL)
npm test                       # Run all 374 tests
npm run validate:components    # Component render validation
npm run validate:render        # React render testing
npm run test:watch             # Watch mode for development

# Quality Assurance  
npm run validate:syntax        # Syntax validation
npm run validate:quick         # Quick validation suite
npm run qa:pre-commit          # Pre-commit checks

# Deployment
npm run deploy:pre-check       # Pre-deployment validation
npm run deploy:verify          # Post-deployment verification

🧩 Component Development Standards

React Component Guidelines

1. Function Declaration Order (CRITICAL)

Always define functions BEFORE useEffect hooks that reference them:

// ✅ CORRECT: Functions defined first
const MyComponent = ({ onComplete }) => {
  const [state, setState] = React.useState(null);
  
  // Define functions BEFORE useEffect
  const handleNext = React.useCallback(() => {
    // Implementation
  }, [dependencies]);
  
  const handlePrevious = React.useCallback(() => {
    // Implementation  
  }, [dependencies]);
  
  // useEffect comes AFTER function definitions
  React.useEffect(() => {
    // Safe to use handleNext and handlePrevious
  }, [handleNext, handlePrevious]);
  
  return React.createElement('div', null, 'Content');
};

// ❌ INCORRECT: Will cause "Cannot access before initialization"
const MyComponent = ({ onComplete }) => {
  // useEffect references functions not yet defined
  React.useEffect(() => {
    handleNext(); // ERROR: handleNext not defined yet
  }, [handleNext, handlePrevious]);
  
  // Functions defined AFTER useEffect (causes errors)
  const handleNext = React.useCallback(() => {
    // Implementation
  }, [dependencies]);
};

2. Component Export Pattern

// Window export for script tag loading
window.MyComponent = MyComponent;

// Or with validation
if (typeof window !== 'undefined') {
  window.MyComponent = MyComponent;
}

3. State Management

// Use useState for local state
const [localState, setLocalState] = React.useState(initialValue);

// Use useCallback for functions in dependencies
const memoizedFunction = React.useCallback(() => {
  // Implementation
}, [dependency1, dependency2]);

// Use useEffect for side effects
React.useEffect(() => {
  // Side effect logic
  return () => {
    // Cleanup
  };
}, [dependencies]);

Error Handling Standards

// Always wrap risky operations in try-catch
const saveData = React.useCallback(() => {
  try {
    localStorage.setItem('key', JSON.stringify(data));
  } catch (error) {
    console.error('Failed to save data:', error);
    // Handle error gracefully
  }
}, [data]);

// Use error boundaries for component crashes
const ComponentWithErrorBoundary = () => {
  return React.createElement(
    window.ErrorBoundary,
    { fallback: 'Something went wrong' },
    React.createElement(MyComponent)
  );
};

🧪 Testing Requirements

Mandatory Testing Before Deployment

All 374 Tests Must Pass

npm test
# Must show: ✅ Tests Passed: 374, ❌ Tests Failed: 0

Component Validation

npm run validate:components
# Must show: ✅ All components validated successfully!

Syntax Validation

npm run validate:syntax
# Must show: ✅ All files syntax validated

Test-Driven Development Process

Write Test First

test.describe('New Feature', () => {
  test.it('should handle new requirement', () => {
    // Test implementation
    const result = myNewFunction(input);
    test.assertEqual(result, expectedOutput);
  });
});

Implement Feature
- Write minimal code to make test pass
- Follow component development standards
- Ensure proper function ordering

Validate Implementation

npm test                    # All tests pass
npm run validate:components # Component validation passes

Component Testing Standards

// Test component can render without errors
test.describe('MyComponent', () => {
  test.it('should render without initialization errors', () => {
    const container = document.createElement('div');
    const root = ReactDOM.createRoot(container);
    
    // Should not throw
    test.assertNoThrow(() => {
      root.render(React.createElement(MyComponent));
    });
    
    root.unmount();
  });
});

🔧 Development Workflow

Feature Development Process

Create Feature Branch

git checkout -b feature/new-feature-name

Run Pre-Development Validation

npm run validate:pre-work
# Runs: validate:quick + npm test

Develop with Testing

# Watch mode for continuous testing
npm run test:watch

# Validate components continuously
npm run validate:components

Pre-Commit Validation

npm run qa:pre-commit
# Comprehensive quality checks

Commit and Push

git add .
git commit -m "feat: descriptive commit message"
git push origin feature/new-feature-name

Hotfix Process

For critical production issues:

Create Hotfix Branch

git checkout -b hotfix/issue-description

Fix Issue with Testing

# Fix the issue
# Add/update tests
npm test  # Must pass all 374 tests
npm run validate:components  # Must pass

Deploy Hotfix

# Commit fix
git commit -m "🚨 HOTFIX: description of fix"

# Push to main
git push origin hotfix/issue-description

# Create PR for review
# After merge, hotfix deploys automatically

📦 Version Management

Version Update Process

# Update version (updates all 121+ locations)
node scripts/update-version.js 7.3.7

# Commit version update
git commit -m "chore: Bump version to v7.3.7"

# Push for deployment
git push origin main

Cache Busting

All scripts automatically include version parameters:

<script src="src/components/MyComponent.js?v=7.3.6"></script>

🛡️ Security Development

Input Validation

// Always validate inputs
const validateInput = (value, type) => {
  if (type === 'number') {
    const num = parseFloat(value);
    return !isNaN(num) && isFinite(num) ? num : 0;
  }
  
  if (type === 'string') {
    return String(value).trim();
  }
  
  return value;
};

XSS Prevention

// Use textContent, not innerHTML
element.textContent = userInput;

// Use React.createElement for safe DOM creation
return React.createElement('div', {
  className: 'safe-content'
}, sanitizedContent);

Secret Protection

Never commit API keys or secrets
Use environment variables for sensitive data
Run npm run security:scan before commits

🚀 Deployment Standards

Pre-Deployment Checklist

[ ] All 374 tests passing
```
npm test
```
[ ] Component render validation passing
```
npm run validate:components
```
[ ] Version bumped correctly
```
node scripts/update-version.js X.Y.Z
```
[ ] Documentation updated
- README.md "What's New" section
- CHANGELOG.md entry
[ ] No console errors in browser
- Test locally with npm run preview
- Check browser console for errors
[ ] Component validation in CI/CD
- GitHub Actions includes component validation
- Automated deployment only after validation passes

Deployment Process

Automatic Deployment
- Push to main triggers GitHub Actions
- CI/CD runs all tests and validations
- Deploys to production if all checks pass

Manual Deployment Check

npm run deploy:pre-check  # Pre-deployment validation
npm run deploy:verify     # Post-deployment verification

🔍 Debugging & Monitoring

Console Interceptor

Debug mode available with ?debug=true URL parameter:

https://ypollak2.github.io/advanced-retirement-planner/?debug=true

Debug Features

Captures all console output
Categorizes logs (calculation, data, api, component)
Export capabilities (JSON, Text, LLM-optimized)
Search and filter functionality

Performance Monitoring

// Performance tracking built-in
console.log('📊 js_load_time: 240ms');
console.log('📊 js_size: 18864ms');

📚 Additional Resources

Documentation

Architecture Guide - System architecture
Testing Guide - Comprehensive testing
Security Features - Security measures
QA Process - Quality assurance

Key Files

CLAUDE.md - Development standards and rules
package.json - Scripts and dependencies
version.json - Version management
.github/workflows/ - CI/CD pipelines

npm Scripts Reference

# Development
npm run dev                    # Development server
npm run build                  # Production build
npm run preview                # Preview build

# Testing (CRITICAL)
npm test                       # All 374 tests
npm run validate:components    # Component validation
npm run validate:syntax        # Syntax validation
npm run validate:quick         # Quick validation

# Quality Assurance
npm run qa:pre-commit          # Pre-commit checks
npm run qa:full                # Full QA suite

# Deployment
npm run deploy:pre-check       # Pre-deployment validation
npm run deploy:verify          # Post-deployment verification

🎯 Best Practices Summary

Always define functions before useEffect that references them
Run npm test before every commit (374 tests must pass)
Use npm run validate:components before deployment
Follow React.useCallback patterns for functions in dependencies
Update documentation alongside code changes
Use try-catch for error-prone operations
Validate all user inputs
Test components can mount/unmount without errors
Follow semantic versioning for releases
Monitor production with debug tools when needed

Remember: The #1 rule is 100% test pass rate before ANY deployment. Component validation prevents production crashes. Follow these standards to maintain the high quality and reliability of the Advanced Retirement Planner.

FilesExpand file tree

Development-Guide.md

Latest commit

History