Skip to content

IMPLEMENTATION_GAPS.md

Latest commit

 

History

History
392 lines (314 loc) · 12.8 KB

IMPLEMENTATION_GAPS.md

File metadata and controls

392 lines (314 loc) · 12.8 KB

StackFastPro Implementation Gaps Analysis

Date: November 16, 2025
Source: Codebase Review Document Analysis
Purpose: Detailed mapping of what exists vs. what's needed

Gap Analysis by System

1. Rules Engine ❌ CRITICAL GAP

What Exists

  • ✅ Complete type definitions (Rule, Diagnostic, EvaluationResult)
  • ✅ Worker wrapper structure (makeRulesWorker())
  • ✅ Fallback mechanism skeleton
  • ✅ 30-40 rules defined in rules.json

What's Missing

  • ❌ Core evaluation logic - No function that processes rules
  • ❌ Rule type handlers - No implementation for each rule kind
  • ❌ Diagnostic generation - No code that creates Diagnostic objects
  • ❌ Score calculation - No implementation of the scoring formula
  • ❌ Worker message handling - Worker script is empty/incomplete

Impact

BLOCKER - Without this, the app cannot validate tool selections or show compatibility scores. This is the core feature.

Files to Implement

src/engine/rules-engine.ts          ← Main evaluation logic
src/engine/rules-engine.worker.ts   ← Worker script
src/engine/score-calculator.ts      ← Scoring algorithm (may not exist yet)
src/engine/diagnostics-builder.ts   ← Diagnostic creation (may not exist yet)

2. Score Calculator ❌ CRITICAL GAP

What Exists

  • ✅ ScoreBreakdown type defined
  • ✅ Formula documented in design.md
  • ✅ Constants defined (base: 50, max bonus: +40, max penalty: -70)

What's Missing

  • ❌ calculateScore() function - No actual implementation
  • ❌ Bonus/penalty aggregation - No code that sums weights
  • ❌ CapabilityCompat cap - No enforcement of +12 limit
  • ❌ Score clamping - No code that clamps to [0, 100]

Impact

BLOCKER - Score is the primary feedback mechanism. Without it, users can't assess their stack quality.

Files to Implement

src/engine/score-calculator.ts      ← Create this file
src/engine/rules-engine.ts          ← Call calculateScore() here

Implementation Notes

// Expected signature
function calculateScore(diagnostics: Diagnostic[]): ScoreBreakdown {
  const base = 50;
  const bonuses = diagnostics.filter(d => (d.weight ?? 0) > 0);
  const penalties = diagnostics.filter(d => (d.weight ?? 0) < 0);
  
  // Cap capabilityCompat bonuses at +12 total
  const capabilityBonuses = bonuses.filter(d => d.category === 'capabilityCompat');
  const capabilitySum = Math.min(
    capabilityBonuses.reduce((sum, d) => sum + (d.weight ?? 0), 0),
    12
  );
  
  const otherBonuses = bonuses.filter(d => d.category !== 'capabilityCompat');
  const otherSum = otherBonuses.reduce((sum, d) => sum + (d.weight ?? 0), 0);
  
  const totalBonuses = Math.min(capabilitySum + otherSum, 40);
  const totalPenalties = Math.max(
    penalties.reduce((sum, d) => sum + (d.weight ?? 0), 0),
    -70
  );
  
  const total = Math.max(0, Math.min(100, base + totalBonuses + totalPenalties));
  
  return {
    base,
    bonuses: bonuses.map(d => ({ reason: d.message, weight: d.weight! })),
    penalties: penalties.map(d => ({ reason: d.message, weight: d.weight! })),
    total
  };
}

3. Suggestion Engine ❌ HIGH PRIORITY GAP

What Exists

  • ✅ Suggestion type defined
  • ✅ suggestions.ts file exists
  • ✅ 5 baseline rules documented in design.md

What's Missing

  • ❌ Suggestion rule implementations - File is empty or skeleton only
  • ❌ Condition functions - No logic to detect when to suggest
  • ❌ Generate functions - No logic to create Suggestion objects
  • ❌ Safety checks - No guards for tool.supports?.dbs

Impact

HIGH - Suggestions are a key differentiator. Without them, users miss out on intelligent recommendations.

Files to Implement

src/data/suggestions.ts             ← Implement 5 baseline rules
src/hooks/useSuggestions.ts         ← Wire to context
src/context/SuggestionsContext.tsx  ← Populate with logic

Implementation Notes

// Expected structure in suggestions.ts
export const suggestionRules = [
  {
    id: 'frontend-to-database',
    condition: (selections: Tool[]) => 
      selections.some(t => t.categoryId === 'frontend') &&
      !selections.some(t => t.categoryId === 'database'),
    generate: (selections: Tool[], tools: Tool[]): Suggestion => ({
      id: 'suggest-database',
      priority: 'high',
      reason: 'Most web applications need data storage',
      targetCategoryId: 'database',
      suggestedToolId: 'postgres',
      action: 'select-tool'
    })
  },
  // ... 4 more rules
];

4. Export System ❌ HIGH PRIORITY GAP

What Exists

  • ✅ ExportRecipe type defined
  • ✅ Template files exist (package-json.ts, readme.ts, env-example.ts)
  • ✅ Recipe directory structure (src/data/recipes/)
  • ✅ Export generator files exist (export-generator.ts, recipe-matcher.ts)

What's Missing

  • ❌ Actual recipes - No recipe files in src/data/recipes/
  • ❌ Recipe matching logic - recipe-matcher.ts is empty/incomplete
  • ❌ Recipe merger - No implementation of merge strategies
  • ❌ File generators - Template files are empty/incomplete
  • ❌ Export log generator - No implementation
  • ❌ Archive generator - No JSZip integration

Impact

HIGH - Export is the final deliverable. Without it, users can't get their project files.

Files to Implement

src/data/recipes/nextjs-base.ts                 ← Create
src/data/recipes/nextjs-prisma-postgres.ts      ← Create
src/data/recipes/nextjs-clerk.ts                ← Create
src/data/recipes/stripe-integration.ts          ← Create
src/data/recipes/index.ts                       ← Create registry
src/lib/recipe-matcher.ts                       ← Implement matching
src/lib/export-generator.ts                     ← Implement generation
src/lib/export-log-generator.ts                 ← Implement logging
src/lib/archive-generator.ts                    ← Implement ZIP
src/templates/package-json.ts                   ← Implement generator
src/templates/readme.ts                         ← Implement generator
src/templates/env-example.ts                    ← Implement generator

Implementation Priority

  1. First: Create 1 simple recipe (nextjs-base.ts)
  2. Second: Implement recipe matcher and merger
  3. Third: Implement file generators
  4. Fourth: Add more recipes
  5. Fifth: Implement archive generator

5. UI Components 🟡 PARTIAL GAP

What Exists

  • ✅ All component files created
  • ✅ shadcn/ui components installed
  • ✅ Component structure defined

What's Missing

  • ❌ State connections - Components not wired to contexts
  • ❌ Event handlers - No onClick, onChange implementations
  • ❌ Data rendering - Components don't display real data
  • ❌ Collapsible behavior - CategorySection doesn't collapse
  • ❌ Radio button groups - ToolSelector doesn't enforce cardinality
  • ❌ Diagnostic display - DiagnosticList doesn't show diagnostics
  • ❌ Score visualization - CompatibilityScore doesn't show score
  • ❌ Suggestion cards - SmartSuggestion doesn't render suggestions

Impact

MEDIUM - UI exists but is non-functional. Needs wiring to make interactive.

Files to Update

src/components/StackBuilder.tsx         ← Wire to all contexts
src/components/CategorySection.tsx      ← Add collapsible, wire to selections
src/components/ToolSelector.tsx         ← Add radio buttons, wire to selections
src/components/DiagnosticList.tsx       ← Wire to evaluation context
src/components/CompatibilityScore.tsx   ← Wire to evaluation context
src/components/SmartSuggestion.tsx      ← Wire to suggestions context
src/components/ExportDialog.tsx         ← Wire to export context

6. State Management 🟡 PARTIAL GAP

What Exists

  • ✅ All context files created
  • ✅ Context structure defined
  • ✅ Hook files created

What's Missing

  • ❌ Context implementations - Providers are empty shells
  • ❌ State logic - No useState, useReducer implementations
  • ❌ Actions - No selectTool(), deselectTool(), etc.
  • ❌ Side effects - No useEffect for rule evaluation
  • ❌ localStorage persistence - No save/load logic
  • ❌ Debouncing - No debounced evaluation

Impact

MEDIUM - State management is the glue between UI and engine. Without it, nothing works together.

Files to Implement

src/context/SelectionsContext.tsx       ← Implement state + actions
src/context/EvaluationContext.tsx       ← Implement evaluation trigger
src/context/SuggestionsContext.tsx      ← Implement suggestion generation
src/context/ExportContext.tsx           ← Implement export state
src/hooks/useStackSelection.ts          ← Implement selection logic
src/hooks/useRulesEngine.ts             ← Implement evaluation hook
src/hooks/useSuggestions.ts             ← Implement suggestion hook
src/hooks/useExport.ts                  ← Implement export hook

7. Testing ❌ COMPLETE GAP

What Exists

  • ✅ Test setup file (src/test/setup.ts)
  • ✅ Vitest configured
  • ✅ Test directories exist (tests/unit/, tests/integration/, etc.)

What's Missing

  • ❌ All tests - No test files exist
  • ❌ Unit tests - Rules engine, suggestion engine, export generator
  • ❌ Integration tests - User flows
  • ❌ Snapshot tests - Export outputs
  • ❌ Performance benchmarks - Rule evaluation timing
  • ❌ Accessibility tests - axe-core, keyboard navigation

Impact

MEDIUM - Tests ensure quality but aren't blockers for initial functionality.

Files to Create

tests/unit/rules-engine.test.ts
tests/unit/suggestion-engine.test.ts
tests/unit/export-generator.test.ts
tests/unit/score-calculator.test.ts
tests/integration/user-flows.test.tsx
tests/integration/export-flows.test.tsx
tests/snapshots/package-json.test.ts
tests/snapshots/readme.test.ts
tests/snapshots/export-log.test.ts
tests/performance/benchmarks.test.ts
tests/accessibility/a11y.test.tsx

8. Data Catalog ✅ COMPLETE

What Exists

  • ✅ categories.json - All 10 categories defined
  • ✅ tools.json - 30+ tools across all categories
  • ✅ rules.json - 30-40 compatibility rules
  • ✅ manifest.json - Catalog versioning

What's Missing

  • ✅ Nothing - Data layer is complete!

Impact

NONE - This is the one area that's fully implemented.

Priority Matrix

🔴 Critical (Must Have for MVP)

  1. Rules Engine - Core evaluation logic
  2. Score Calculator - Scoring algorithm
  3. State Management - SelectionsContext + EvaluationContext
  4. UI Wiring - Connect components to state

🟠 High Priority (Core Features)

  1. Suggestion Engine - 5 baseline rules
  2. Export System - Recipes + generators
  3. UI Components - Complete implementations

🟡 Medium Priority (Quality)

  1. Testing - Unit + integration tests
  2. Polish - Loading states, error handling
  3. Accessibility - WCAG compliance verification

🟢 Low Priority (Nice to Have)

  1. Performance optimization - If targets not met
  2. Additional recipes - Beyond MVP set
  3. Documentation - User guides, API docs

Recommended Implementation Order

Week 1: Core Engine

  1. Implement rules engine evaluation logic
  2. Implement score calculator
  3. Test with sample data
  4. Verify Worker communication

Week 2: State & UI

  1. Implement SelectionsContext
  2. Implement EvaluationContext
  3. Wire StackBuilder to contexts
  4. Wire CategorySection + ToolSelector
  5. Wire CompatibilityScore + DiagnosticList

Week 3: Suggestions & Export

  1. Implement suggestion rules
  2. Wire SmartSuggestion component
  3. Create 4 export recipes
  4. Implement recipe matcher + merger
  5. Implement file generators
  6. Wire ExportDialog

Week 4: Testing & Polish

  1. Write unit tests
  2. Write integration tests
  3. Write snapshot tests
  4. Run accessibility tests
  5. Add loading states + error handling
  6. Implement responsive design
  7. Final QA and bug fixes

Success Criteria

Functional Completeness

  • User can select tools from all categories
  • Score updates in real-time
  • Diagnostics show conflicts/synergies
  • Suggestions appear contextually
  • Export generates working files

Quality Metrics

  • 80%+ code coverage
  • <50ms rule evaluation
  • WCAG 2.1 AA compliance
  • Zero critical bugs

User Experience

  • Intuitive interface
  • Clear error messages
  • Helpful suggestions
  • Smooth export flow
  • Responsive design

Conclusion

The codebase has a solid foundation with complete types, data, and structure. The main gaps are in implementation logic - the "brains" of the system. By focusing on the critical path (rules engine → state → UI → export), we can deliver a working MVP in 4 weeks.

Next Step: Start with Phase 1 (Core Engine) and implement the rules engine evaluation logic.