@vue-skuilder/db 0.1.18 → 0.1.21

package/tests/core/navigators/navigators.test.ts

@@ -1,27 +1,23 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect } from 'vitest';
 import { ContentNavigator, WeightedCard, getCardOrigin } from '../../../src/core/navigators/index';
-import { StudySessionNewItem, StudySessionReviewItem } from '../../../src/core';
-import { ScheduledCard } from '../../../src/core/types/user';
 
-// Mock implementation of ContentNavigator for testing the default getWeightedCards
+// Mock implementation of ContentNavigator for testing base class behavior
 class MockNavigator extends ContentNavigator {
-  private mockNewCards: StudySessionNewItem[] = [];
-  private mockReviews: (StudySessionReviewItem & ScheduledCard)[] = [];
-
-  setMockNewCards(cards: StudySessionNewItem[]) {
-    this.mockNewCards = cards;
-  }
+  name: string = 'MockNavigator';
+  // Base class no longer has legacy methods - subclasses must implement getWeightedCards
+}
 
-  setMockReviews(reviews: (StudySessionReviewItem & ScheduledCard)[]) {
-    this.mockReviews = reviews;
-  }
+// Mock implementation that properly implements getWeightedCards
+class ProperMockNavigator extends ContentNavigator {
+  name: string = 'ProperMockNavigator';
+  private cards: WeightedCard[] = [];
 
-  async getNewCards(n?: number): Promise<StudySessionNewItem[]> {
-    return this.mockNewCards.slice(0, n);
+  setCards(cards: WeightedCard[]) {
+    this.cards = cards;
   }
 
-  async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
-    return this.mockReviews;
+  async getWeightedCards(limit: number): Promise<WeightedCard[]> {
+    return this.cards.slice(0, limit);
   }
 }
 
@@ -77,111 +73,97 @@ describe('WeightedCard', () => {
   });
 });
 
-describe('ContentNavigator.getWeightedCards', () => {
-  let navigator: MockNavigator;
+describe('ContentNavigator base class', () => {
+  it('should throw error when getWeightedCards is not implemented', async () => {
+    const navigator = new MockNavigator();
 
-  beforeEach(() => {
-    navigator = new MockNavigator();
+    await expect(navigator.getWeightedCards(10)).rejects.toThrow(
+      'must implement getWeightedCards()'
+    );
   });
 
-  it('should return empty array when no cards available', async () => {
-    navigator.setMockNewCards([]);
-    navigator.setMockReviews([]);
-
-    const result = await navigator.getWeightedCards(10);
+  it('should throw error mentioning legacy methods have been removed', async () => {
+    const navigator = new MockNavigator();
 
-    expect(result).toEqual([]);
-  });
-
-  it('should assign score=1.0 to all cards by default', async () => {
-    navigator.setMockNewCards([
-      {
-        cardID: 'card-1',
-        courseID: 'course-1',
-        contentSourceType: 'course',
-        contentSourceID: 'course-1',
-        status: 'new',
-      },
-      {
-        cardID: 'card-2',
-        courseID: 'course-1',
-        contentSourceType: 'course',
-        contentSourceID: 'course-1',
-        status: 'new',
-      },
-    ]);
-
-    const result = await navigator.getWeightedCards(10);
-
-    expect(result).toHaveLength(2);
-    expect(result[0].score).toBe(1.0);
-    expect(result[1].score).toBe(1.0);
-  });
-
-  it('should mark new cards with source="new"', async () => {
-    navigator.setMockNewCards([
-      {
-        cardID: 'card-1',
-        courseID: 'course-1',
-        contentSourceType: 'course',
-        contentSourceID: 'course-1',
-        status: 'new',
-      },
-    ]);
-
-    const result = await navigator.getWeightedCards(10);
-
-    expect(getCardOrigin(result[0])).toBe('new');
-    expect(result[0].provenance[0].reason).toContain('new');
+    await expect(navigator.getWeightedCards(10)).rejects.toThrow();
   });
+});
 
-  it('should mark reviews with origin="review"', async () => {
-    navigator.setMockReviews([
+describe('ContentNavigator.getWeightedCards with proper implementation', () => {
+  it('should return cards from implementation', async () => {
+    const navigator = new ProperMockNavigator();
+    navigator.setCards([
       {
-        cardID: 'review-1',
-        courseID: 'course-1',
-        contentSourceType: 'course',
-        contentSourceID: 'course-1',
-        status: 'review',
-        reviewID: 'review-id-1',
-        _id: 'scheduled-1',
-        cardId: 'review-1',
+        cardId: 'card-1',
         courseId: 'course-1',
-        scheduledFor: 'course',
-        schedulingAgentId: 'agent-1',
-        reviewTime: new Date(),
-        scheduledAt: new Date(),
-      } as unknown as StudySessionReviewItem & ScheduledCard,
+        score: 0.8,
+        provenance: [
+          {
+            strategy: 'test',
+            strategyName: 'Test',
+            strategyId: 'TEST',
+            action: 'generated',
+            score: 0.8,
+            reason: 'Test new card',
+          },
+        ],
+      },
     ]);
 
     const result = await navigator.getWeightedCards(10);
 
-    expect(getCardOrigin(result[0])).toBe('review');
-    expect(result[0].provenance[0].reason).toContain('review');
+    expect(result).toHaveLength(1);
+    expect(result[0].cardId).toBe('card-1');
+    expect(result[0].score).toBe(0.8);
   });
 
   it('should respect limit parameter', async () => {
-    navigator.setMockNewCards([
+    const navigator = new ProperMockNavigator();
+    navigator.setCards([
       {
-        cardID: 'card-1',
-        courseID: 'course-1',
-        contentSourceType: 'course',
-        contentSourceID: 'course-1',
-        status: 'new',
+        cardId: 'card-1',
+        courseId: 'course-1',
+        score: 0.9,
+        provenance: [
+          {
+            strategy: 'test',
+            strategyName: 'Test',
+            strategyId: 'TEST',
+            action: 'generated',
+            score: 0.9,
+            reason: 'Test new card',
+          },
+        ],
       },
       {
-        cardID: 'card-2',
-        courseID: 'course-1',
-        contentSourceType: 'course',
-        contentSourceID: 'course-1',
-        status: 'new',
+        cardId: 'card-2',
+        courseId: 'course-1',
+        score: 0.8,
+        provenance: [
+          {
+            strategy: 'test',
+            strategyName: 'Test',
+            strategyId: 'TEST',
+            action: 'generated',
+            score: 0.8,
+            reason: 'Test new card',
+          },
+        ],
       },
       {
-        cardID: 'card-3',
-        courseID: 'course-1',
-        contentSourceType: 'course',
-        contentSourceID: 'course-1',
-        status: 'new',
+        cardId: 'card-3',
+        courseId: 'course-1',
+        score: 0.7,
+        provenance: [
+          {
+            strategy: 'test',
+            strategyName: 'Test',
+            strategyId: 'TEST',
+            action: 'generated',
+            score: 0.7,
+            reason: 'Test new card',
+          },
+        ],
       },
     ]);
 
@@ -190,57 +172,42 @@ describe('ContentNavigator.getWeightedCards', () => {
     expect(result).toHaveLength(2);
   });
 
-  it('should combine new cards and reviews', async () => {
-    navigator.setMockNewCards([
-      {
-        cardID: 'new-1',
-        courseID: 'course-1',
-        contentSourceType: 'course',
-        contentSourceID: 'course-1',
-        status: 'new',
-      },
-    ]);
-    navigator.setMockReviews([
-      {
-        cardID: 'review-1',
-        courseID: 'course-1',
-        contentSourceType: 'course',
-        contentSourceID: 'course-1',
-        status: 'review',
-        reviewID: 'review-id-1',
-        _id: 'scheduled-1',
-        cardId: 'review-1',
-        courseId: 'course-1',
-        scheduledFor: 'course',
-        schedulingAgentId: 'agent-1',
-        reviewTime: new Date(),
-        scheduledAt: new Date(),
-      } as unknown as StudySessionReviewItem & ScheduledCard,
-    ]);
-
-    const result = await navigator.getWeightedCards(10);
-
-    expect(result).toHaveLength(2);
-    const origins = result.map((c) => getCardOrigin(c));
-    expect(origins).toContain('new');
-    expect(origins).toContain('review');
-  });
-
-  it('should correctly map cardID to cardId and courseID to courseId', async () => {
-    navigator.setMockNewCards([
-      {
-        cardID: 'CARD-123',
-        courseID: 'COURSE-456',
-        contentSourceType: 'course',
-        contentSourceID: 'COURSE-456',
-        status: 'new',
-      },
-    ]);
+  it('should correctly identify card origins from provenance', () => {
+    const newCard: WeightedCard = {
+      cardId: 'new-1',
+      courseId: 'course-1',
+      score: 1.0,
+      provenance: [
+        {
+          strategy: 'test',
+          strategyName: 'Test',
+          strategyId: 'TEST',
+          action: 'generated',
+          score: 1.0,
+          reason: 'ELO distance 50, new card',
+        },
+      ],
+    };
 
-    const result = await navigator.getWeightedCards(10);
+    const reviewCard: WeightedCard = {
+      cardId: 'review-1',
+      courseId: 'course-1',
+      score: 0.8,
+      reviewID: 'SCHEDULED_CARD-123',
+      provenance: [
+        {
+          strategy: 'srs',
+          strategyName: 'SRS',
+          strategyId: 'SRS',
+          action: 'generated',
+          score: 0.8,
+          reason: '48h overdue (interval: 72h), review',
+        },
+      ],
+    };
 
-    expect(result[0].cardId).toBe('CARD-123');
-    expect(result[0].courseId).toBe('COURSE-456');
+    expect(getCardOrigin(newCard)).toBe('new');
+    expect(getCardOrigin(reviewCard)).toBe('review');
   });
 });
 

package/docs/todo-pipeline-optimization.md

@@ -1,117 +0,0 @@
-# TODO: Pipeline Optimization - Batch Tag Hydration
-
-## Status: NOT STARTED
-
-## Problem
-
-Each filter strategy independently queries for card tags, resulting in redundant database operations.
-
-For N cards through 3 filters = 3N tag lookups, when N would suffice.
-
-```typescript
-// In HierarchyDefinitionNavigator
-const tagResponse = await context.course.getAppliedTags(card.cardId);
-
-// In InterferenceMitigatorNavigator  
-const tagResponse = await context.course.getAppliedTags(card.cardId);
-
-// In RelativePriorityNavigator
-const tagResponse = await context.course.getAppliedTags(card.cardId);
-```
-
-## Proposed Solution: Hydrate Tags in WeightedCard
-
-Extend `WeightedCard` to optionally carry pre-fetched tag data:
-
-```typescript
-interface WeightedCard {
-  cardId: string;
-  courseId: string;
-  score: number;
-  provenance: StrategyContribution[];
-  
-  /** Pre-fetched tags. If present, filters should use this instead of querying. */
-  tags?: string[];
-}
-```
-
-### Implementation Steps
-
-#### Step 1: Add batch tag lookup method
-
-```typescript
-// In CourseDBInterface
-getAppliedTagsBatch(cardIds: string[]): Promise<Map<string, string[]>>;
-```
-
-#### Step 2: Update WeightedCard type
-
-Add optional `tags?: string[]` field to `WeightedCard` in `core/navigators/index.ts`.
-
-#### Step 3: Hydrate in Pipeline
-
-The `Pipeline` class should batch-fetch tags after getting candidates from the generator:
-
-```typescript
-async getWeightedCards(limit: number): Promise<WeightedCard[]> {
-  const context = await this.buildContext();
-  let cards = await this.generator.getWeightedCards(fetchLimit, context);
-  
-  // Batch hydrate tags
-  cards = await this.hydrateTags(cards);
-  
-  for (const filter of this.filters) {
-    cards = await filter.transform(cards, context);
-  }
-  
-  return cards.filter(c => c.score > 0)
-              .sort((a, b) => b.score - a.score)
-              .slice(0, limit);
-}
-
-private async hydrateTags(cards: WeightedCard[]): Promise<WeightedCard[]> {
-  const cardIds = cards.map(c => c.cardId);
-  const tagsByCard = await this.course.getAppliedTagsBatch(cardIds);
-  
-  return cards.map(c => ({
-    ...c,
-    tags: tagsByCard.get(c.cardId) ?? []
-  }));
-}
-```
-
-#### Step 4: Update filter strategies
-
-Each filter checks for pre-hydrated tags before querying:
-
-```typescript
-const cardTags = card.tags ?? await this.getCardTags(card.cardId, context.course);
-```
-
-#### Step 5: Add tests
-
-- Verify tags are populated by Pipeline
-- Verify filters use pre-fetched tags when available
-- Verify fallback works if tags missing
-
-## Files to Modify
-
-| File | Change |
-|------|--------|
-| `core/navigators/index.ts` | Add `tags?` to `WeightedCard` |
-| `core/interfaces/courseDB.ts` | Add `getAppliedTagsBatch()` |
-| `impl/couch/courseDB.ts` | Implement `getAppliedTagsBatch()` |
-| `impl/static/courseDB.ts` | Implement `getAppliedTagsBatch()` |
-| `core/navigators/Pipeline.ts` | Add `hydrateTags()` step |
-| `core/navigators/hierarchyDefinition.ts` | Use `card.tags` if available |
-| `core/navigators/interferenceMitigator.ts` | Use `card.tags` if available |
-| `core/navigators/relativePriority.ts` | Use `card.tags` if available |
-
-## Performance Expectations
-
-| Scenario | Before | After |
-|----------|--------|-------|
-| 20 cards, 3 filters | 60 tag queries | 1 batch query (20 cards) |
-| 50 cards, 4 filters | 200 tag queries | 1 batch query (50 cards) |
-
-Batch queries also reduce round-trip overhead compared to individual queries.