Skip to content

PHASING_AND_TDD_PLAN.md

Latest commit

 

History

History
654 lines (471 loc) · 14.9 KB

PHASING_AND_TDD_PLAN.md

File metadata and controls

654 lines (471 loc) · 14.9 KB

Phasing Strategy & TDD/Verification Plan

Recommended Phasing Strategy

Phase 1: Core UI System Terminology (Week 1-2)

Scope: Migrate core UI base classes to Skin system terminology

Changes:

  1. VisualNeuron → SkinCell
  2. SensoryNeuron → Receptor
  3. MotorNeuron → Effector
  4. InterneuronUI → DermalLayer
  5. VisualAstrocyte → Adipocyte
  6. VisualOligodendrocyte → Melanocyte
  7. ComponentProps → System-specific props
  8. ComponentState → System-specific state

Rationale: Foundation for all UI components. Must be done first.

Dependencies: None

Risk: Critical - Breaking changes to core UI system

Estimated Effort: 2 weeks

Phase 2: UI Component Names (Week 3-4)

Scope: Rename generic UI components to medical equivalents

Changes:

  1. Button → TouchReceptor
  2. Input → TextReceptor
  3. Select → SelectReceptor / ChoiceReceptor
  4. Form → DermalLayer
  5. Modal → Membrane / Vesicle
  6. Card → DermalLayer / Epidermis
  7. Alert → AlertReceptor / Nociceptor
  8. Text → Keratinocyte / TextCell
  9. Radio → RadioReceptor / ChoiceReceptor
  10. Checkbox → CheckReceptor / ToggleReceptor

Rationale: Depends on Phase 1. Components extend base classes.

Dependencies: Phase 1

Risk: High - Breaking changes to component library

Estimated Effort: 2 weeks

Phase 3: Visualization System (Week 5-6)

Scope: Rename visualization components to medical equivalents

Changes:

  1. Chart → Visualization
  2. BarChart → BarVisualization
  3. LineChart → LineVisualization
  4. PieChart → PieVisualization
  5. ScatterPlot → ScatterVisualization
  6. ChartDataPoint → DataPoint / Measurement
  7. DataBounds → Bounds / Range
  8. CanvasPoint → Coordinate / Point
  9. BaseChartProps → BaseVisualizationProps
  10. BaseChartState → BaseVisualizationState
  11. ChartTheme → VisualizationTheme

Rationale: Independent of UI system changes. Can be done in parallel with Phase 2.

Dependencies: None (but extends VisualNeuron which becomes SkinCell in Phase 1)

Risk: Medium - Breaking changes to visualization system

Estimated Effort: 2 weeks

Phase 4: Communication System (Week 7)

Scope: Migrate communication terms to Circulatory System

Changes:

  1. EventBus → Heart / Artery
  2. Event → BloodCell / Signal

Rationale: Independent system. Can be done in parallel.

Dependencies: None

Risk: Medium - Breaking changes to communication system

Estimated Effort: 1 week

Phase 5: Respiratory System (Week 8-9)

Scope: Rename respiratory system terms to medical equivalents

Changes:

  1. Router → Bronchus / Trachea
  2. Resource → Oxygen / Nutrient
  3. ResourcePool → Alveolus / Capillary
  4. Route → Bronchiole
  5. DatabaseResource → DatabaseOxygen / DatabaseNutrient
  6. CacheResource → CacheOxygen / CacheNutrient
  7. StorageResource → StorageOxygen / StorageNutrient
  8. RestAdapter → RestBronchus
  9. GraphQLAdapter → GraphQLBronchus
  10. WebSocketAdapter → WebSocketBronchus
  11. ProtocolAdapter → ProtocolBronchus

Rationale: Independent system. Can be done in parallel.

Dependencies: None

Risk: Medium - Breaking changes to respiratory system

Estimated Effort: 2 weeks

Phase 6: Infrastructure Terms (Week 10)

Scope: Rename infrastructure terms to medical equivalents

Changes:

  1. Server → Organ / System
  2. Client → Receptor / Effector
  3. Bridge → Synapse / Connection
  4. WebSocketBridge → WebSocketSynapse / WebSocketConnection
  5. TheaterServer → TheaterOrgan / TheaterSystem
  6. ClientConnection → ReceptorConnection / EffectorConnection
  7. HotReload → Regeneration / Renewal
  8. ServerConfig → OrganConfig / SystemConfig
  9. ServerState → OrganState / SystemState
  10. WebSocketConfig → WebSocketConnectionConfig
  11. HotReloadConfig → RegenerationConfig

Rationale: Independent system. Can be done in parallel.

Dependencies: None

Risk: Medium - Breaking changes to infrastructure

Estimated Effort: 1 week

Phase 7: Tools & Testing Terms (Week 11)

Scope: Rename tools and testing terms to medical equivalents

Changes:

  1. DependencyAuditor → DependencyAnalyzer / DependencyInspector
  2. AuditReport → AnalysisReport / InspectionReport
  3. AuditOptions → AnalysisOptions / InspectionOptions
  4. Test → Experiment / Hypothesis (in test files)
  5. Mock → Specimen / Model (in test files)

Rationale: Less critical. Can be done last.

Dependencies: None

Risk: Low - Internal tools, less breaking

Estimated Effort: 1 week

TDD/Verification Plan

Phase 1: Core UI System Terminology

Test Strategy

  1. Before Refactoring:

    • Write tests asserting new terminology (SkinCell, Receptor, etc.)
    • Write tests for backward compatibility (if needed)
    • Document expected behavior

  2. During Refactoring:

    • Run existing tests to identify breaking changes
    • Update test imports to use new names
    • Update test class names (TestVisualNeuron → TestSkinCell)
    • Update test type references (ComponentProps → SkinCellProps)

  3. After Refactoring:

    • Run full test suite
    • Verify all tests pass
    • Check for any remaining old terminology
    • Verify exports work correctly

Test Adaptation Steps

  1. Update Test Imports:

    // Before
import { VisualNeuron } from '../VisualNeuron';

// After
import { SkinCell } from '../SkinCell';

  2. Update Test Class Names:

    // Before
class TestVisualNeuron extends VisualNeuron<...> {}

// After
class TestSkinCell extends SkinCell<...> {}

  3. Update Type References:

    // Before
class TestComponent extends VisualNeuron<ComponentProps, ComponentState> {}

// After
class TestComponent extends SkinCell<SkinCellProps, SkinCellState> {}

  4. Update Test Assertions:

    // Before
expect(component).toBeInstanceOf(VisualNeuron);

// After
expect(component).toBeInstanceOf(SkinCell);

Verification Steps

  1. Type Checking:

    • Run npm run type-check
    • Verify no type errors
    • Verify all imports resolve correctly

  2. Test Execution:

    • Run npm test
    • Verify all tests pass
    • Check test coverage remains >90%

  3. Build Verification:

    • Run npm run build
    • Verify build succeeds
    • Verify no compilation errors

  4. Export Verification:

    • Check src/ui/index.ts exports
    • Verify all exports work
    • Test imports from external packages

Phase 2: UI Component Names

Test Strategy

  1. Before Refactoring:

    • Write tests asserting new component names
    • Document component behavior

  2. During Refactoring:

    • Update component class names
    • Update component file names
    • Update component imports
    • Update component type references

  3. After Refactoring:

    • Run component tests
    • Verify all components work
    • Check stories still work

Test Adaptation Steps

  1. Update Component Imports:

    // Before
import { Button } from '../components/Button';

// After
import { TouchReceptor } from '../components/TouchReceptor';

  2. Update Component Usage:

    // Before
const button = new Button({ ... });

// After
const button = new TouchReceptor({ ... });

  3. Update Component Types:

    // Before
const props: ButtonProps = { ... };

// After
const props: TouchReceptorProps = { ... };

Verification Steps

  1. Component Tests:

    • Run component-specific tests
    • Verify all components render correctly
    • Verify all components handle interactions correctly

  2. Story Verification:

    • Run Storybook
    • Verify all stories work
    • Verify component names in stories

  3. Integration Tests:

    • Run integration tests
    • Verify components work together
    • Verify no breaking changes

Phase 3: Visualization System

Test Strategy

  1. Before Refactoring:

    • Write tests asserting new visualization names
    • Document visualization behavior

  2. During Refactoring:

    • Update visualization class names
    • Update visualization file names
    • Update visualization imports
    • Update visualization type references

  3. After Refactoring:

    • Run visualization tests
    • Verify all visualizations render correctly
    • Check data visualization works

Test Adaptation Steps

  1. Update Visualization Imports:

    // Before
import { BarChart } from '../visualization/BarChart';

// After
import { BarVisualization } from '../visualization/BarVisualization';

  2. Update Visualization Usage:

    // Before
const chart = new BarChart({ ... });

// After
const chart = new BarVisualization({ ... });

  3. Update Visualization Types:

    // Before
const props: BarChartProps = { ... };

// After
const props: BarVisualizationProps = { ... };

Verification Steps

  1. Visualization Tests:

    • Run visualization-specific tests
    • Verify all visualizations render correctly
    • Verify data visualization works

  2. Visual Verification:

    • Manually verify visualizations render correctly
    • Verify charts display data correctly
    • Verify interactions work

Phase 4: Communication System

Test Strategy

  1. Before Refactoring:

    • Write tests asserting new communication names
    • Document communication behavior

  2. During Refactoring:

    • Update communication class names
    • Update communication imports
    • Update communication type references

  3. After Refactoring:

    • Run communication tests
    • Verify event bus works correctly
    • Check message routing works

Test Adaptation Steps

  1. Update Communication Imports:

    // Before
import { EventBus } from '../communication/EventBus';

// After
import { Heart } from '../circulatory/core/Heart';
// OR
import { Artery } from '../circulatory/core/Artery';

  2. Update Communication Usage:

    // Before
const eventBus = new EventBus();

// After
const heart = new Heart();
// OR
const artery = new Artery('event-stream');

Verification Steps

  1. Communication Tests:

    • Run communication-specific tests
    • Verify event bus works correctly
    • Verify message routing works

  2. Integration Tests:

    • Run integration tests
    • Verify communication between systems works
    • Verify no breaking changes

Phase 5: Respiratory System

Test Strategy

  1. Before Refactoring:

    • Write tests asserting new respiratory names
    • Document respiratory behavior

  2. During Refactoring:

    • Update respiratory class names
    • Update respiratory imports
    • Update respiratory type references

  3. After Refactoring:

    • Run respiratory tests
    • Verify routing works correctly
    • Check resource management works

Test Adaptation Steps

  1. Update Respiratory Imports:

    // Before
import { Router } from '../respiratory/resources/Router';

// After
import { Bronchus } from '../respiratory/resources/Bronchus';

  2. Update Respiratory Usage:

    // Before
const router = new Router({ ... });

// After
const bronchus = new Bronchus({ ... });

Verification Steps

  1. Respiratory Tests:

    • Run respiratory-specific tests
    • Verify routing works correctly
    • Verify resource management works

  2. Integration Tests:

    • Run integration tests
    • Verify respiratory system works with other systems
    • Verify no breaking changes

Phase 6: Infrastructure Terms

Test Strategy

  1. Before Refactoring:

    • Write tests asserting new infrastructure names
    • Document infrastructure behavior

  2. During Refactoring:

    • Update infrastructure class names
    • Update infrastructure imports
    • Update infrastructure type references

  3. After Refactoring:

    • Run infrastructure tests
    • Verify server works correctly
    • Check hot reload works

Test Adaptation Steps

  1. Update Infrastructure Imports:

    // Before
import { TheaterServer } from '../theater/server/TheaterServer';

// After
import { TheaterOrgan } from '../theater/server/TheaterOrgan';

  2. Update Infrastructure Usage:

    // Before
const server = new TheaterServer({ ... });

// After
const organ = new TheaterOrgan({ ... });

Verification Steps

  1. Infrastructure Tests:

    • Run infrastructure-specific tests
    • Verify server works correctly
    • Verify hot reload works

  2. Integration Tests:

    • Run integration tests
    • Verify infrastructure works with other systems
    • Verify no breaking changes

Phase 7: Tools & Testing Terms

Test Strategy

  1. Before Refactoring:

    • Write tests asserting new tool names
    • Document tool behavior

  2. During Refactoring:

    • Update tool class names
    • Update tool imports
    • Update tool type references

  3. After Refactoring:

    • Run tool tests
    • Verify tools work correctly
    • Check testing infrastructure works

Test Adaptation Steps

  1. Update Tool Imports:

    // Before
import { DependencyAuditor } from '../tools/dependency-auditor';

// After
import { DependencyAnalyzer } from '../tools/dependency-analyzer';

  2. Update Tool Usage:

    // Before
const auditor = new DependencyAuditor();

// After
const analyzer = new DependencyAnalyzer();

Verification Steps

  1. Tool Tests:

    • Run tool-specific tests
    • Verify tools work correctly
    • Verify analysis works

  2. Testing Infrastructure:

    • Run test suite
    • Verify testing infrastructure works
    • Verify no breaking changes

General TDD Principles

1. Write Tests First

Before refactoring, write tests that assert the new terminology:

  • Test that new class names exist
  • Test that new class names work correctly
  • Test that old class names are deprecated (if backward compatibility needed)

2. Update Tests During Refactoring

As you refactor:

  • Update test imports
  • Update test class names
  • Update test type references
  • Update test assertions

3. Verify After Refactoring

After refactoring:

  • Run full test suite
  • Verify all tests pass
  • Check test coverage
  • Verify no regressions

4. Backward Compatibility (If Needed)

If backward compatibility is required:

  • Create deprecated aliases
  • Add deprecation warnings
  • Document migration path
  • Plan removal timeline

Verification Checklist

For each phase:

  • All tests pass
  • Type checking passes
  • Build succeeds
  • Exports work correctly
  • Documentation updated
  • No old terminology remains
  • Integration tests pass
  • Performance not degraded
  • No breaking changes (or documented)

Last Updated: 2024 Status: Phasing & TDD Plan Complete