@thesimonharms/basa 0.1.0

package/test/CardView.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from 'vitest';
+import { CardView } from '../src/tui/CardView.js';
+import type { ReviewCard } from '../src/flashcards/types.js';
+import { freshState } from '../src/flashcards/srs.js';
+import type { KeyEvent } from '@mudah-cli/terminal';
+
+function key(name: string, ch?: string): KeyEvent {
+  return { name, ch, kind: 'press' };
+}
+
+function makeCard(front: string, back: string): ReviewCard {
+  return { card: { front, back }, state: freshState(0) };
+}
+
+describe('CardView', () => {
+  it('renders the front text and a "press space to reveal" prompt', async () => {
+    const view = new CardView({
+      deckPath: '/tmp/x.yml',
+      cellsWidth: 60,
+      cellsHeight: 16,
+      onGraded: () => {},
+      onSkip: () => {},
+    });
+    await view.setCard(makeCard('hola', 'hello'));
+    const rows = view.render();
+    const all = rows.join('\n');
+    expect(all).toContain('hola');
+    expect(all).toContain('reveal');
+    expect(all).not.toContain('hello');
+  });
+
+  it('space reveals the back and renders the answer', async () => {
+    let grade = -1;
+    const view = new CardView({
+      deckPath: '/tmp/x.yml',
+      cellsWidth: 60,
+      cellsHeight: 16,
+      onGraded: (g) => { grade = g; },
+      onSkip: () => {},
+    });
+    await view.setCard(makeCard('hola', 'hello'));
+    view.onKey(key('space'));
+    // Drive the reveal animation to completion.
+    for (let i = 0; i < 20; i++) view.tick();
+    const all = view.render().join('\n');
+    expect(all).toContain('hello');
+    expect(grade).toBe(-1);
+  });
+
+  it('keys 1..4 grade after reveal; 0 → Again, 3 → Easy', async () => {
+    const grades: number[] = [];
+    const view = new CardView({
+      deckPath: '/tmp/x.yml',
+      cellsWidth: 60,
+      cellsHeight: 16,
+      onGraded: (g) => grades.push(g),
+      onSkip: () => {},
+    });
+    await view.setCard(makeCard('a', 'A'));
+    view.onKey(key('space'));
+    for (let i = 0; i < 20; i++) view.tick();
+    view.onKey(key('1'));
+    expect(grades).toEqual([0]);
+
+    await view.setCard(makeCard('b', 'B'));
+    view.onKey(key('space'));
+    for (let i = 0; i < 20; i++) view.tick();
+    view.onKey(key('4'));
+    expect(grades).toEqual([0, 3]);
+  });
+
+  it('keys 1..4 grade after reveal even when the live KeyEvent carries ch (real parseKeys output)', async () => {
+    // parseKeys emits digits as { name: '1', ch: '1', kind: 'press' } — see
+    // @mudah-cli/terminal/keys.js. The keymap must not buffer the digit into
+    // the typed-answer field before the grade switch has a chance to run.
+    const grades: number[] = [];
+    const typed: string[] = [];
+    const view = new CardView({
+      deckPath: '/tmp/x.yml',
+      cellsWidth: 60,
+      cellsHeight: 16,
+      onGraded: (g, t) => { grades.push(g); typed.push(t); },
+      onSkip: () => {},
+    });
+    await view.setCard(makeCard('a', 'A'));
+    view.onKey(key('space'));
+    for (let i = 0; i < 20; i++) view.tick();
+    view.onKey({ name: '1', ch: '1', kind: 'press' });
+    expect(grades).toEqual([0]);
+    expect(typed).toEqual(['']);
+  });
+
+  it('keys 1..4 do nothing before reveal', async () => {
+    const grades: number[] = [];
+    const view = new CardView({
+      deckPath: '/tmp/x.yml',
+      cellsWidth: 60,
+      cellsHeight: 16,
+      onGraded: (g) => grades.push(g),
+      onSkip: () => {},
+    });
+    await view.setCard(makeCard('a', 'A'));
+    view.onKey(key('1'));
+    expect(grades).toEqual([]);
+  });
+
+  it('typing buffers characters and backspace removes them', async () => {
+    const view = new CardView({
+      deckPath: '/tmp/x.yml',
+      cellsWidth: 60,
+      cellsHeight: 16,
+      onGraded: () => {},
+      onSkip: () => {},
+    });
+    await view.setCard(makeCard('a', 'A'));
+    view.onKey(key('h', 'h'));
+    view.onKey(key('e', 'e'));
+    view.onKey(key('l', 'l'));
+    view.onKey(key('l', 'l'));
+    view.onKey(key('o', 'o'));
+    let all = view.render().join('\n');
+    expect(all).toContain('hello');
+
+    view.onKey(key('backspace'));
+    all = view.render().join('\n');
+    expect(all).toContain('hell');
+  });
+
+  it('"n" skips without grading', async () => {
+    let skipped = false;
+    const view = new CardView({
+      deckPath: '/tmp/x.yml',
+      cellsWidth: 60,
+      cellsHeight: 16,
+      onGraded: () => {},
+      onSkip: () => { skipped = true; },
+    });
+    await view.setCard(makeCard('a', 'A'));
+    view.onKey(key('n'));
+    expect(skipped).toBe(true);
+  });
+
+  it('setCard(undefined) shows the done view', async () => {
+    const view = new CardView({
+      deckPath: '/tmp/x.yml',
+      cellsWidth: 60,
+      cellsHeight: 16,
+      onGraded: () => {},
+      onSkip: () => {},
+    });
+    await view.setCard(undefined, { reviewed: 5, again: 1, hard: 1, good: 2, easy: 1 });
+    const all = view.render().join('\n');
+    expect(all).toContain('session complete');
+    expect(all).toContain('reviewed');
+    expect(all).toContain('5');
+  });
+});

package/test/deck.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from 'vitest';
+import { loadDeck, saveReviewCards, loadReviewCards, createDeck, DeckLoadError, listDecks, defaultDecksDir } from '../src/flashcards/deck.js';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { freshState, grade } from '../src/flashcards/srs.js';
+
+async function withTempDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = await mkdtemp(join(tmpdir(), 'basa-test-'));
+  try {
+    return await fn(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+describe('deck loading', () => {
+  it('loads a YAML deck with string sides', async () => {
+    await withTempDir(async (dir) => {
+      const file = join(dir, 'greetings.yml');
+      await writeFile(
+        file,
+        'name: greetings\ncards:\n  - front: hola\n    back: hello\n  - front: adios\n    back: goodbye\n',
+        'utf8',
+      );
+      const deck = await loadDeck(file);
+      expect(deck.name).toBe('greetings');
+      expect(deck.cards).toHaveLength(2);
+      expect(deck.cards[0]?.front).toBe('hola');
+      expect(deck.cards[0]?.back).toBe('hello');
+    });
+  });
+
+  it('loads a JSON deck with field-list sides', async () => {
+    await withTempDir(async (dir) => {
+      const file = join(dir, 'jp.json');
+      await writeFile(
+        file,
+        JSON.stringify({
+          name: 'jp',
+          cards: [
+            {
+              front: [{ text: 'こんにちは' }, { image: './konnichiwa.png' }],
+              back: 'hello',
+            },
+          ],
+        }),
+        'utf8',
+      );
+      const deck = await loadDeck(file);
+      const first = deck.cards[0];
+      expect(Array.isArray(first?.front)).toBe(true);
+      const fields = first?.front as Array<Record<string, string>>;
+      expect(fields[0]?.text).toBe('こんにちは');
+      expect(fields[1]?.image).toBe('./konnichiwa.png');
+    });
+  });
+
+  it('rejects a deck without a name', async () => {
+    await withTempDir(async (dir) => {
+      const file = join(dir, 'bad.yml');
+      await writeFile(file, 'cards: []\n', 'utf8');
+      await expect(loadDeck(file)).rejects.toBeInstanceOf(DeckLoadError);
+    });
+  });
+
+  it('rejects a card missing back', async () => {
+    await withTempDir(async (dir) => {
+      const file = join(dir, 'bad.yml');
+      await writeFile(file, 'name: x\ncards:\n  - front: hi\n', 'utf8');
+      await expect(loadDeck(file)).rejects.toThrow(/missing front or back/);
+    });
+  });
+
+  it('rejects a field with no text/image/audio', async () => {
+    await withTempDir(async (dir) => {
+      const file = join(dir, 'bad.json');
+      await writeFile(file, JSON.stringify({ name: 'x', cards: [{ front: [{}], back: 'b' }] }), 'utf8');
+      await expect(loadDeck(file)).rejects.toThrow(/has no text, image, or audio/);
+    });
+  });
+
+  it('persists and re-loads SRS state', async () => {
+    await withTempDir(async (dir) => {
+      const file = join(dir, 'd.yml');
+      await writeFile(file, 'name: d\ncards:\n  - front: a\n    back: A\n  - front: b\n    back: B\n', 'utf8');
+      const deck = await loadDeck(file);
+      const initial = await loadReviewCards(deck, file);
+      const reviewed = initial.map((rc, i) => ({
+        ...rc,
+        state: grade(rc.state, 2 as const, 1_000 + i * 1000),
+      }));
+      await saveReviewCards(file, reviewed);
+
+      const reloaded = await loadReviewCards(deck, file);
+      expect(reloaded[0]?.state.streak).toBe(1);
+      expect(reloaded[0]?.state.reviews).toBe(1);
+      expect(reloaded[1]?.state.streak).toBe(1);
+    });
+  });
+
+  it('corrupt progress file is ignored, fresh state returned', async () => {
+    await withTempDir(async (dir) => {
+      const file = join(dir, 'd.yml');
+      await writeFile(file, 'name: d\ncards:\n  - front: a\n    back: A\n', 'utf8');
+      const deck = await loadDeck(file);
+      await writeFile(`${file}.progress.json`, '{ this is not json');
+      const cards = await loadReviewCards(deck, file);
+      expect(cards[0]?.state.streak).toBe(0);
+    });
+  });
+
+  it('createDeck writes a scaffold file', async () => {
+    await withTempDir(async (dir) => {
+      const file = join(dir, 'new.yml');
+      const path = await createDeck(file, 'New Deck');
+      expect(path).toBe(file);
+      const deck = await loadDeck(file);
+      expect(deck.name).toBe('New Deck');
+      expect(deck.cards.length).toBeGreaterThan(0);
+    });
+  });
+
+  it('listDecks finds YAML and JSON files', async () => {
+    await withTempDir(async (dir) => {
+      await writeFile(join(dir, 'a.yml'), 'name: a\ncards: []\n', 'utf8');
+      await writeFile(join(dir, 'b.yaml'), 'name: b\ncards: []\n', 'utf8');
+      await writeFile(join(dir, 'c.json'), '{"name":"c","cards":[]}', 'utf8');
+      await writeFile(join(dir, 'README.md'), 'ignored', 'utf8');
+      const files = await listDecks(dir);
+      expect(files).toHaveLength(3);
+      expect(files.some((f) => f.endsWith('a.yml'))).toBe(true);
+      expect(files.some((f) => f.endsWith('b.yaml'))).toBe(true);
+      expect(files.some((f) => f.endsWith('c.json'))).toBe(true);
+    });
+  });
+});
+
+describe('defaultDecksDir', () => {
+  it('returns a path under the home directory', () => {
+    const dir = defaultDecksDir();
+    expect(dir).toMatch(/\/basa\/decks$/);
+  });
+});

package/test/effects.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { confettiRows, shakeRows, typeOnRows } from '../src/tui/effects.js';
+
+describe('typeOnRows', () => {
+  it('returns 1 row at frame 0 (the floor)', () => {
+    const rows = typeOnRows({ durationFrames: 4, frame: 0 }, ['a', 'b', 'c']);
+    expect(rows.length).toBe(1);
+  });
+
+  it('returns all rows after the duration', () => {
+    const rows = typeOnRows({ durationFrames: 4, frame: 4 }, ['a', 'b', 'c']);
+    expect(rows).toEqual(['a', 'b', 'c']);
+  });
+
+  it('reveals progressively with each frame', () => {
+    const a = typeOnRows({ durationFrames: 4, frame: 1 }, ['a', 'b', 'c', 'd']);
+    const b = typeOnRows({ durationFrames: 4, frame: 2 }, ['a', 'b', 'c', 'd']);
+    expect(a.length).toBeLessThanOrEqual(b.length);
+  });
+});
+
+describe('shakeRows', () => {
+  it('is a no-op at the end of the animation', () => {
+    const rows = shakeRows({ durationFrames: 4, frame: 4 }, ['hi'], 42);
+    expect(rows).toEqual(['hi']);
+  });
+
+  it('shifts rows horizontally mid-animation', () => {
+    const rows = shakeRows({ durationFrames: 8, frame: 0 }, ['hi'], 42);
+    // Amplitude is 3 at frame 0, so a shift of up to 3 chars is possible.
+    const shifted = rows[0] !== 'hi';
+    expect(typeof shifted).toBe('boolean');
+  });
+});
+
+describe('confettiRows', () => {
+  it('emits the requested number of rows', () => {
+    const rows = confettiRows({ frame: 0, durationFrames: 10, seed: 1, width: 20, palette: ['\x1b[0m'] }, 5);
+    expect(rows).toHaveLength(5);
+    // Visible cell count is the width (ANSI codes don't count).
+    for (const row of rows) {
+      const visible = row.replace(/\x1b\[[0-9;]*m/g, '').length;
+      expect(visible).toBe(20);
+    }
+  });
+
+  it('emits a reset suffix so cells don\'t bleed color', () => {
+    const rows = confettiRows({ frame: 0, durationFrames: 10, seed: 1, width: 10, palette: ['\x1b[31m'] }, 1);
+    expect(rows[0]).toContain('\x1b[0m');
+  });
+});

package/test/halfblock.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import { halfBlockLines, fitToCells } from '../src/flashcards/halfblock.js';
+import { isImagePath } from '../src/flashcards/image.js';
+
+describe('halfBlockLines', () => {
+  it('emits one row per 2 pixels of height', () => {
+    const pixels = new Uint8Array(4 * 4 * 4); // 4x4, all zero (black)
+    const lines = halfBlockLines({ width: 4, height: 4, pixels });
+    expect(lines).toHaveLength(2);
+    for (const line of lines) {
+      expect(line).toContain('\x1b[0m');
+      expect(line).toContain('▀');
+    }
+  });
+
+  it('emits color codes per row when pixels differ', () => {
+    const pixels = new Uint8Array(2 * 2 * 4);
+    // Row 0 (top), col 0: red.
+    pixels[0] = 255; pixels[1] = 0; pixels[2] = 0;
+    // Row 0, col 1: green.
+    pixels[4] = 0; pixels[5] = 255; pixels[6] = 0;
+    // Row 1 (bottom), col 0: blue.
+    pixels[8] = 0; pixels[9] = 0; pixels[10] = 255;
+    // Row 1, col 1: yellow.
+    pixels[12] = 255; pixels[13] = 255; pixels[14] = 0;
+    const lines = halfBlockLines({ width: 2, height: 2, pixels });
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toContain('38;2;255;0;0');
+    expect(lines[0]).toContain('48;2;0;0;255');
+    expect(lines[0]).toContain('38;2;0;255;0');
+    expect(lines[0]).toContain('48;2;255;255;0');
+  });
+});
+
+describe('fitToCells', () => {
+  it('respects a tall narrow source', () => {
+    const { width, height } = fitToCells(100, 1000, 80, 24);
+    expect(width).toBeLessThanOrEqual(80);
+    expect(height).toBeLessThanOrEqual(48);
+  });
+
+  it('respects a wide short source', () => {
+    const { width, height } = fitToCells(1000, 100, 80, 24);
+    expect(width).toBeLessThanOrEqual(80);
+    expect(height).toBeLessThanOrEqual(48);
+  });
+
+  it('returns sane defaults for a zero-size source', () => {
+    const { width, height } = fitToCells(0, 0, 80, 24);
+    expect(width).toBe(1);
+    expect(height).toBe(1);
+  });
+});
+
+describe('isImagePath', () => {
+  it('accepts common image extensions', () => {
+    expect(isImagePath('a.png')).toBe(true);
+    expect(isImagePath('a.PNG')).toBe(true);
+    expect(isImagePath('path/to/a.jpg')).toBe(true);
+    expect(isImagePath('a.jpeg')).toBe(true);
+    expect(isImagePath('a.gif')).toBe(true);
+    expect(isImagePath('a.webp')).toBe(true);
+    expect(isImagePath('a.svg')).toBe(true);
+  });
+
+  it('rejects non-image extensions', () => {
+    expect(isImagePath('a.txt')).toBe(false);
+    expect(isImagePath('README.md')).toBe(false);
+    expect(isImagePath('a')).toBe(false);
+  });
+});

package/test/sound.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { BasaFx } from '../src/flashcards/sound.js';
+
+describe('BasaFx', () => {
+  it('opens without error even with no audio backend available', async () => {
+    const fx = await BasaFx.open();
+    expect(typeof fx.isLive).toBe('boolean');
+    await fx.dispose();
+  });
+
+  it('isLive is false in CI environments', async () => {
+    const fx = await BasaFx.open();
+    if (process.env.CI !== undefined) {
+      expect(fx.isLive).toBe(false);
+    }
+    await fx.dispose();
+  });
+
+  it('playCorrect and playIncorrect are no-ops on silent instance', async () => {
+    const fx = await BasaFx.open();
+    // Both must not throw regardless of backend availability.
+    await fx.playCorrect(2);
+    await fx.playCorrect(3);
+    await fx.playIncorrect();
+    await fx.dispose();
+  });
+});

package/test/srs.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+import { freshState, grade, isDue, pickNext } from '../src/flashcards/srs.js';
+import type { ReviewCard } from '../src/flashcards/types.js';
+
+describe('SRS algorithm', () => {
+  it('freshState starts due immediately', () => {
+    const s = freshState(1_000);
+    expect(s.due).toBeNull();
+    expect(s.streak).toBe(0);
+    expect(s.ease).toBe(2.5);
+    expect(s.intervalDays).toBe(0);
+    expect(s.reviews).toBe(0);
+    expect(s.lastGrade).toBe(null);
+  });
+
+  it('Again resets streak, drops ease, and re-queues in 10 minutes', () => {
+    const s = freshState(0);
+    const next = grade(s, 0, 0);
+    expect(next.streak).toBe(0);
+    expect(next.ease).toBeLessThan(2.5);
+    expect(next.intervalDays).toBe(0);
+    expect(next.due).toBe(10 * 60 * 1000);
+    expect(next.reviews).toBe(1);
+    expect(next.lastGrade).toBe(0);
+  });
+
+  it('Good progresses 1 day → 6 days → scaling', () => {
+    const s = freshState(0);
+    const day = 24 * 60 * 60 * 1000;
+    const s1 = grade(s, 2, 0);
+    expect(s1.intervalDays).toBe(1);
+    expect(s1.due).toBe(day);
+    expect(s1.streak).toBe(1);
+
+    const s2 = grade(s1, 2, 0);
+    expect(s2.intervalDays).toBe(6);
+    expect(s2.streak).toBe(2);
+
+    const s3 = grade(s2, 2, 0);
+    expect(s3.intervalDays).toBeGreaterThanOrEqual(6);
+    expect(s3.streak).toBe(3);
+  });
+
+  it('Easy bumps ease; Hard drops it; Good holds', () => {
+    const s = freshState(0);
+    const easy = grade(s, 3, 0);
+    expect(easy.ease).toBeGreaterThan(2.5);
+    const hard = grade(s, 1, 0);
+    expect(hard.ease).toBeLessThan(2.5);
+    const good = grade(s, 2, 0);
+    expect(good.ease).toBe(2.5);
+  });
+
+  it('ease is clamped to [1.3, 2.8]', () => {
+    let s = freshState(0);
+    for (let i = 0; i < 20; i++) s = grade(s, 1, 0);
+    expect(s.ease).toBeGreaterThanOrEqual(1.3);
+    let s2 = freshState(0);
+    for (let i = 0; i < 20; i++) s2 = grade(s2, 3, 0);
+    expect(s2.ease).toBeLessThanOrEqual(2.8);
+  });
+
+  it('isDue returns true when due is null or in the past', () => {
+    expect(isDue({ ...freshState(0), due: null }, 1000)).toBe(true);
+    expect(isDue({ ...freshState(0), due: 500 }, 1000)).toBe(true);
+    expect(isDue({ ...freshState(0), due: 1500 }, 1000)).toBe(false);
+  });
+
+  it('pickNext returns the oldest-due card, or undefined if none due', () => {
+    const cards: ReviewCard[] = [
+      { card: { front: 'a', back: 'A' }, state: { ...freshState(0), due: 100 } },
+      { card: { front: 'b', back: 'B' }, state: { ...freshState(0), due: 50 } },
+      { card: { front: 'c', back: 'C' }, state: { ...freshState(0), due: 200 } },
+    ];
+    const next = pickNext(cards, 1000);
+    expect(next?.card.front).toBe('b');
+  });
+
+  it('pickNext returns undefined when no cards are due', () => {
+    const cards: ReviewCard[] = [
+      { card: { front: 'a', back: 'A' }, state: { ...freshState(0), due: 5_000_000 } },
+    ];
+    expect(pickNext(cards, 1000)).toBeUndefined();
+  });
+});

package/test/study.command.test.ts

@@ -0,0 +1,26 @@
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { TestApp } from '@mudah-cli/mudah/testing';
+
+const appDir = fileURLToPath(new URL('..', import.meta.url));
+
+describe('study command', () => {
+  it('rejects when no deck is given and the default dir is empty', async () => {
+    const app = await TestApp.create({ cwd: appDir, env: { BASA_DECKS_DIR: '/tmp/basa-empty-test-dir' } });
+    // BasaConfig reads `app.decksDir`; with no env override the test's
+    // HOME will be a temp dir. Just ensure the command fails gracefully
+    // if there's nothing to study.
+    const result = await app.dispatch(['study']);
+    expect(result.code).not.toBe(0);
+  });
+});
+
+describe('list command', () => {
+  it('reports no decks when the directory is empty', async () => {
+    const app = await TestApp.create({ cwd: appDir });
+    const result = await app.dispatch(['list']);
+    // The test's HOME-derived default dir may or may not have decks; just
+    // verify the command exits cleanly.
+    expect([0, 1]).toContain(result.code);
+  });
+});