|
| 1 | +import { describe, it, expect } from "vitest"; |
| 2 | +import { gradeCard, cardFromRow } from "./flashcards.js"; |
| 3 | + |
| 4 | +/** |
| 5 | + * Characterization tests (issue #549) — these capture current behaviour of |
| 6 | + * `cardFromRow`/`gradeCard` in mcp-server/src/tools/flashcards.ts so a later |
| 7 | + * refactor shows up as a visible test diff. Do NOT change source behaviour |
| 8 | + * to make these pass; if source is wrong, the test documents the bug. |
| 9 | + */ |
| 10 | + |
| 11 | +const NOW = new Date("2026-07-26T12:00:00.000Z"); |
| 12 | + |
| 13 | +type FsrsRow = Parameters<typeof cardFromRow>[0]; |
| 14 | + |
| 15 | +/** A row that has never been through FSRS — the SM-2/pre-migration shape. */ |
| 16 | +function freshRow(overrides: Partial<FsrsRow> = {}): FsrsRow { |
| 17 | + return { |
| 18 | + interval_days: 0, |
| 19 | + repetitions: 0, |
| 20 | + due_at: NOW.toISOString(), |
| 21 | + last_reviewed_at: null, |
| 22 | + stability: null, |
| 23 | + difficulty: null, |
| 24 | + fsrs_state: 0, |
| 25 | + lapses: 0, |
| 26 | + learning_steps: 0, |
| 27 | + elapsed_days: 0, |
| 28 | + ...overrides, |
| 29 | + }; |
| 30 | +} |
| 31 | + |
| 32 | +/** A fully FSRS-populated row (as a migration-seeded / previously-graded row would be). */ |
| 33 | +function populatedRow(overrides: Partial<FsrsRow> = {}): FsrsRow { |
| 34 | + return { |
| 35 | + interval_days: 6, |
| 36 | + repetitions: 3, |
| 37 | + due_at: "2026-07-30T00:00:00.000Z", |
| 38 | + last_reviewed_at: "2026-07-24T00:00:00.000Z", |
| 39 | + stability: 12.34, |
| 40 | + difficulty: 5.67, |
| 41 | + fsrs_state: 2, // Review |
| 42 | + lapses: 1, |
| 43 | + learning_steps: 0, |
| 44 | + elapsed_days: 6, |
| 45 | + ...overrides, |
| 46 | + }; |
| 47 | +} |
| 48 | + |
| 49 | +describe("cardFromRow", () => { |
| 50 | + it("returns a fresh empty card when stability is null", () => { |
| 51 | + const row = freshRow({ stability: null, difficulty: 5 }); |
| 52 | + const card = cardFromRow(row, NOW); |
| 53 | + expect(card.state).toBe(0); // State.New |
| 54 | + expect(card.stability).toBe(0); |
| 55 | + expect(card.difficulty).toBe(0); |
| 56 | + expect(card.reps).toBe(0); |
| 57 | + expect(card.lapses).toBe(0); |
| 58 | + expect(card.due).toEqual(NOW); |
| 59 | + expect(card.last_review).toBeUndefined(); |
| 60 | + }); |
| 61 | + |
| 62 | + it("returns a fresh empty card when difficulty is null", () => { |
| 63 | + const row = freshRow({ stability: 5, difficulty: null }); |
| 64 | + const card = cardFromRow(row, NOW); |
| 65 | + expect(card.state).toBe(0); // State.New |
| 66 | + expect(card.stability).toBe(0); |
| 67 | + expect(card.difficulty).toBe(0); |
| 68 | + expect(card.due).toEqual(NOW); |
| 69 | + expect(card.last_review).toBeUndefined(); |
| 70 | + }); |
| 71 | + |
| 72 | + it("returns a fresh empty card when both stability and difficulty are null", () => { |
| 73 | + const row = freshRow(); |
| 74 | + const card = cardFromRow(row, NOW); |
| 75 | + expect(card.state).toBe(0); |
| 76 | + expect(card.due).toEqual(NOW); |
| 77 | + }); |
| 78 | + |
| 79 | + it("round-trips a fully populated row onto the Card", () => { |
| 80 | + const row = populatedRow(); |
| 81 | + const card = cardFromRow(row, NOW); |
| 82 | + expect(card.stability).toBe(row.stability); |
| 83 | + expect(card.difficulty).toBe(row.difficulty); |
| 84 | + expect(card.reps).toBe(row.repetitions); |
| 85 | + expect(card.lapses).toBe(row.lapses); |
| 86 | + expect(card.state).toBe(row.fsrs_state); |
| 87 | + expect(card.scheduled_days).toBe(row.interval_days); |
| 88 | + expect(card.elapsed_days).toBe(row.elapsed_days); |
| 89 | + expect(card.learning_steps).toBe(row.learning_steps); |
| 90 | + expect(card.due).toEqual(new Date(row.due_at)); |
| 91 | + expect(card.last_review).toEqual(new Date(row.last_reviewed_at as string)); |
| 92 | + }); |
| 93 | + |
| 94 | + it("falls back to `now` for last_review when last_reviewed_at is null", () => { |
| 95 | + const row = populatedRow({ last_reviewed_at: null }); |
| 96 | + const card = cardFromRow(row, NOW); |
| 97 | + expect(card.last_review).toEqual(NOW); |
| 98 | + }); |
| 99 | +}); |
| 100 | + |
| 101 | +describe("gradeCard", () => { |
| 102 | + const ratings = ["again", "hard", "good", "easy"] as const; |
| 103 | + |
| 104 | + it.each(ratings)("returns the full persisted-row shape for rating '%s' on a New card", (rating) => { |
| 105 | + const row = freshRow(); |
| 106 | + const result = gradeCard(row, rating, NOW); |
| 107 | + |
| 108 | + expect(result).toMatchObject({ |
| 109 | + stability: expect.any(Number), |
| 110 | + difficulty: expect.any(Number), |
| 111 | + fsrs_state: expect.any(Number), |
| 112 | + lapses: expect.any(Number), |
| 113 | + learning_steps: expect.any(Number), |
| 114 | + elapsed_days: expect.any(Number), |
| 115 | + interval_days: expect.any(Number), |
| 116 | + repetitions: expect.any(Number), |
| 117 | + due_at: expect.any(String), |
| 118 | + last_reviewed_at: expect.any(String), |
| 119 | + }); |
| 120 | + |
| 121 | + // due_at / last_reviewed_at are ISO strings. |
| 122 | + expect(new Date(result.due_at).toISOString()).toBe(result.due_at); |
| 123 | + expect(new Date(result.last_reviewed_at).toISOString()).toBe(result.last_reviewed_at); |
| 124 | + expect(result.last_reviewed_at).toBe(NOW.toISOString()); |
| 125 | + }); |
| 126 | + |
| 127 | + it("orders scheduling further out as rating improves: again < hard < good < easy", () => { |
| 128 | + const row = freshRow(); |
| 129 | + const again = gradeCard(row, "again", NOW); |
| 130 | + const hard = gradeCard(row, "hard", NOW); |
| 131 | + const good = gradeCard(row, "good", NOW); |
| 132 | + const easy = gradeCard(row, "easy", NOW); |
| 133 | + |
| 134 | + const t = (r: ReturnType<typeof gradeCard>) => new Date(r.due_at).getTime(); |
| 135 | + |
| 136 | + expect(t(again)).toBeLessThanOrEqual(t(hard)); |
| 137 | + expect(t(hard)).toBeLessThanOrEqual(t(good)); |
| 138 | + expect(t(good)).toBeLessThan(t(easy)); |
| 139 | + }); |
| 140 | + |
| 141 | + it("rating 'again' on an established Review-state card increments lapses", () => { |
| 142 | + const row = populatedRow({ fsrs_state: 2, lapses: 1 }); |
| 143 | + const result = gradeCard(row, "again", NOW); |
| 144 | + expect(result.lapses).toBe(2); |
| 145 | + }); |
| 146 | + |
| 147 | + it("BUG (#549 §4): a 'lapsed' row (repetitions/interval reset but stability/difficulty null) currently grades as a brand-new card, discarding history", () => { |
| 148 | + // This row represents history that was reset to null stability/difficulty |
| 149 | + // (e.g. a lapse-tracking path) while repetitions/interval_days/last_reviewed_at |
| 150 | + // still carry prior state. Because cardFromRow() only checks |
| 151 | + // stability===null || difficulty===null, this row is treated as a |
| 152 | + // never-seen card: FSRS starts a brand-new learning card, and prior |
| 153 | + // repetitions/interval history is silently discarded. Asserting today's |
| 154 | + // (buggy) behaviour here — do NOT "fix" the source to make this pass. |
| 155 | + const lapsedRow = freshRow({ |
| 156 | + repetitions: 0, |
| 157 | + interval_days: 0, |
| 158 | + last_reviewed_at: "2026-07-20T00:00:00.000Z", |
| 159 | + stability: null, |
| 160 | + difficulty: null, |
| 161 | + }); |
| 162 | + |
| 163 | + const card = cardFromRow(lapsedRow, NOW); |
| 164 | + // Discards history: comes back as a brand-new createEmptyCard(now) — the |
| 165 | + // null-stability/difficulty check short-circuits BEFORE the |
| 166 | + // last_reviewed_at fallback logic even runs, so last_review is left |
| 167 | + // `undefined` (createEmptyCard's default), not `now` and not the row's |
| 168 | + // real last_reviewed_at. |
| 169 | + expect(card.state).toBe(0); // State.New |
| 170 | + expect(card.reps).toBe(0); |
| 171 | + expect(card.last_review).toBeUndefined(); |
| 172 | + |
| 173 | + const result = gradeCard(lapsedRow, "good", NOW); |
| 174 | + // A brand-new "good" grade produces the same result whether or not the |
| 175 | + // row had prior repetitions — because cardFromRow() throws that history away. |
| 176 | + const freshResult = gradeCard(freshRow(), "good", NOW); |
| 177 | + expect(result).toEqual(freshResult); |
| 178 | + }); |
| 179 | +}); |
0 commit comments