saterminal 0.3.2 → 0.5.0

package/src/progress/attempt.ts

@@ -0,0 +1,70 @@
+import type { Difficulty, DomainCode, Question, SkillCode } from "@/questions/question.ts";
+import { checkAnswer } from "@/questions/question.ts";
+
+export type Outcome = "correct" | "incorrect" | "corrected";
+
+export type Attempt = {
+  questionId: string;
+  outcome: Outcome;
+  answeredAt: string;
+  durationSeconds: number;
+  difficulty?: Difficulty;
+  domain?: DomainCode;
+  skill?: SkillCode;
+};
+
+export type AttemptEvent = {
+  questionId: string;
+  correct: boolean;
+  answeredAt: string;
+  durationSeconds: number;
+  difficulty: Difficulty;
+  domain: DomainCode;
+  skill: SkillCode;
+};
+
+export type AnswerRecord = {
+  answer: string;
+  correct: boolean;
+  attempt: Attempt;
+  event: AttemptEvent;
+};
+
+export function createAnswerRecord(
+  previous: Attempt | undefined,
+  question: Question,
+  answer: string,
+  durationSeconds = 0,
+  answeredAt = new Date(),
+): AnswerRecord {
+  const correct = checkAnswer(question, answer);
+  const timestamp = answeredAt.toISOString();
+  return {
+    answer,
+    correct,
+    attempt: {
+      questionId: question.id,
+      outcome: nextOutcome(previous?.outcome, correct),
+      answeredAt: timestamp,
+      durationSeconds,
+      difficulty: question.difficulty,
+      domain: question.domain,
+      skill: question.skill,
+    },
+    event: {
+      questionId: question.id,
+      correct,
+      answeredAt: timestamp,
+      durationSeconds,
+      difficulty: question.difficulty,
+      domain: question.domain,
+      skill: question.skill,
+    },
+  };
+}
+
+export function nextOutcome(previous: Outcome | undefined, correct: boolean): Outcome {
+  if (previous === "correct" || previous === "corrected") return previous;
+  if (previous === "incorrect" && correct) return "corrected";
+  return correct ? "correct" : "incorrect";
+}

package/src/progress/history.ts

@@ -0,0 +1,34 @@
+import type { Attempt } from "@/progress/attempt.ts";
+
+export type HistoryFilters = {
+  wrong?: boolean;
+  corrected?: boolean;
+  limit?: number;
+  since?: string;
+};
+
+export function history(attempts: Iterable<Attempt>, filters: HistoryFilters = {}, now = new Date()): Attempt[] {
+  let rows = [...attempts].sort((a, b) => b.answeredAt.localeCompare(a.answeredAt));
+  if (filters.since) {
+    const since = parseSince(filters.since, now);
+    rows = rows.filter((attempt) => new Date(attempt.answeredAt) >= since);
+  }
+  if (filters.wrong || filters.corrected) {
+    rows = rows.filter((attempt) =>
+      (filters.wrong && attempt.outcome === "incorrect") ||
+      (filters.corrected && attempt.outcome === "corrected")
+    );
+  }
+  return filters.limit ? rows.slice(0, filters.limit) : rows;
+}
+
+export function parseSince(value: string, now = new Date()): Date {
+  const relative = /^(\d+)(d|w)$/.exec(value);
+  if (relative) {
+    const amount = Number(relative[1]) * (relative[2] === "w" ? 7 : 1);
+    return new Date(now.getTime() - amount * 86_400_000);
+  }
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) throw new Error(`Invalid date: ${value}`);
+  return date;
+}

package/src/progress/review-queue.ts

@@ -0,0 +1,44 @@
+import type { Attempt, AttemptEvent } from "@/progress/attempt.ts";
+
+export type ReviewRequirements = {
+  minimumDays: number;
+  minimumAnswersAfter: number;
+};
+
+export function reviewQueue(
+  attempts: Iterable<Attempt>,
+  events: Iterable<AttemptEvent>,
+  requirements: ReviewRequirements,
+  now = new Date(),
+): string[] {
+  const eventTimes = [...events]
+    .map((event) => new Date(event.answeredAt).getTime())
+    .filter(Number.isFinite)
+    .sort((left, right) => left - right);
+  const minimumAge = requirements.minimumDays * 86_400_000;
+  return [...attempts]
+    .filter((attempt) => {
+      if (attempt.outcome !== "incorrect" && attempt.outcome !== "corrected") return false;
+      const answeredAt = new Date(attempt.answeredAt).getTime();
+      return Number.isFinite(answeredAt)
+        && now.getTime() - answeredAt >= minimumAge
+        && answersAfter(eventTimes, answeredAt) >= requirements.minimumAnswersAfter;
+    })
+    .sort((a, b) => priority(a) - priority(b) || a.answeredAt.localeCompare(b.answeredAt))
+    .map((attempt) => attempt.questionId);
+}
+
+function answersAfter(sortedTimes: readonly number[], answeredAt: number): number {
+  let low = 0;
+  let high = sortedTimes.length;
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2);
+    if (sortedTimes[middle] <= answeredAt) low = middle + 1;
+    else high = middle;
+  }
+  return sortedTimes.length - low;
+}
+
+function priority(attempt: Attempt): number {
+  return attempt.outcome === "incorrect" ? 0 : 1;
+}

package/src/progress/statistics.ts

@@ -0,0 +1,35 @@
+import type { Attempt } from "@/progress/attempt.ts";
+
+export type ProgressStatistics = {
+  answered: number;
+  correct: number;
+  incorrect: number;
+  corrected: number;
+  mastered: number;
+  accuracy: number;
+  averageSeconds: number;
+};
+
+export function progressStatistics(attempts: Iterable<Attempt>): ProgressStatistics {
+  const values = [...attempts];
+  let correct = 0;
+  let incorrect = 0;
+  let corrected = 0;
+  let totalSeconds = 0;
+  for (const attempt of values) {
+    if (attempt.outcome === "correct") correct += 1;
+    else if (attempt.outcome === "incorrect") incorrect += 1;
+    else corrected += 1;
+    totalSeconds += attempt.durationSeconds;
+  }
+  const mastered = correct + corrected;
+  return {
+    answered: values.length,
+    correct,
+    incorrect,
+    corrected,
+    mastered,
+    accuracy: values.length === 0 ? 0 : mastered / values.length,
+    averageSeconds: values.length === 0 ? 0 : totalSeconds / values.length,
+  };
+}

package/src/progress/weaknesses.ts

@@ -0,0 +1,44 @@
+import { domainLabels, skillLabels } from "@/questions/taxonomy.ts";
+import type { DomainCode, SkillCode } from "@/questions/question.ts";
+import type { Attempt } from "@/progress/attempt.ts";
+
+export type Weakness = {
+  skill: SkillCode;
+  label: string;
+  domain: DomainCode;
+  domainLabel: string;
+  total: number;
+  mastered: number;
+  missed: number;
+  accuracy: number;
+  averageSeconds: number;
+};
+
+export function weaknesses(attempts: Iterable<Attempt>): Weakness[] {
+  const groups = new Map<SkillCode, Omit<Weakness, "accuracy" | "averageSeconds"> & { totalSeconds: number }>();
+  for (const attempt of attempts) {
+    if (!attempt.skill || !attempt.domain) continue;
+    const row = groups.get(attempt.skill) ?? {
+      skill: attempt.skill,
+      label: skillLabels[attempt.skill],
+      domain: attempt.domain,
+      domainLabel: domainLabels[attempt.domain],
+      total: 0,
+      mastered: 0,
+      missed: 0,
+      totalSeconds: 0,
+    };
+    row.total += 1;
+    row.totalSeconds += attempt.durationSeconds;
+    if (attempt.outcome === "incorrect") row.missed += 1;
+    else row.mastered += 1;
+    groups.set(attempt.skill, row);
+  }
+  return [...groups.values()].map(({ totalSeconds, ...row }) => ({
+    ...row,
+    accuracy: row.total === 0 ? 0 : row.mastered / row.total,
+    averageSeconds: row.total === 0 ? 0 : totalSeconds / row.total,
+  })).sort((a, b) =>
+    b.missed - a.missed || a.accuracy - b.accuracy || b.total - a.total || a.skill.localeCompare(b.skill)
+  );
+}

package/src/questions/focus.ts

@@ -0,0 +1,77 @@
+import type { Difficulty, DomainCode, SkillCode } from "@/questions/question.ts";
+import { difficulties, domains, skills, skillsByDomain } from "@/questions/taxonomy.ts";
+
+export type Focus = {
+  difficulties: Difficulty[];
+  skills: SkillCode[];
+};
+
+export const defaultFocus: Focus = {
+  difficulties: ["M", "H"],
+  skills: [...skills],
+};
+
+export function normalizeFocus(value: unknown): Focus {
+  const raw = value && typeof value === "object"
+    ? value as { difficulties?: unknown; skills?: unknown; domains?: unknown }
+    : {};
+
+  return {
+    difficulties: selection(raw.difficulties, difficulties, defaultFocus.difficulties),
+    skills: normalizedSkills(raw.skills, raw.domains),
+  };
+}
+
+export function selectedDomains(focus: Focus): DomainCode[] {
+  return domains.filter((domain) => skillsByDomain[domain].some((skill) => focus.skills.includes(skill)));
+}
+
+export function toggleDifficulty(focus: Focus, difficulty: Difficulty): Focus {
+  const selected = focus.difficulties.includes(difficulty);
+  if (selected && focus.difficulties.length === 1) return focus;
+  return {
+    ...focus,
+    difficulties: selected
+      ? focus.difficulties.filter((value) => value !== difficulty)
+      : ordered([...focus.difficulties, difficulty], difficulties),
+  };
+}
+
+export function toggleSkill(focus: Focus, skill: SkillCode): Focus {
+  const selected = focus.skills.includes(skill);
+  if (selected && focus.skills.length === 1) return focus;
+  return {
+    ...focus,
+    skills: selected
+      ? focus.skills.filter((value) => value !== skill)
+      : ordered([...focus.skills, skill], skills),
+  };
+}
+
+export function toggleDomain(focus: Focus, domain: DomainCode): Focus {
+  const children = skillsByDomain[domain];
+  const allSelected = children.every((skill) => focus.skills.includes(skill));
+  if (allSelected) {
+    const remaining = focus.skills.filter((skill) => !children.includes(skill));
+    return remaining.length === 0 ? focus : { ...focus, skills: remaining };
+  }
+  return { ...focus, skills: ordered([...new Set([...focus.skills, ...children])], skills) };
+}
+
+function normalizedSkills(value: unknown, legacyDomains: unknown): SkillCode[] {
+  const direct = selection(value, skills, []);
+  if (direct.length > 0) return direct;
+  const selected = selection(legacyDomains, domains, []);
+  if (selected.length > 0) return selected.flatMap((domain) => [...skillsByDomain[domain]]);
+  return [...defaultFocus.skills];
+}
+
+function selection<T extends string>(value: unknown, options: readonly T[], fallback: readonly T[]): T[] {
+  if (!Array.isArray(value)) return [...fallback];
+  const selected = options.filter((option) => value.includes(option));
+  return selected.length > 0 ? selected : [...fallback];
+}
+
+function ordered<T extends string>(values: readonly T[], order: readonly T[]): T[] {
+  return order.filter((value) => values.includes(value));
+}

package/src/questions/local-bank.ts

@@ -0,0 +1,133 @@
+import { mkdir, rename, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { questionBankCachePath } from "@/local-data/paths.ts";
+import type { Focus } from "@/questions/focus.ts";
+import type { Question } from "@/questions/question.ts";
+
+export const questionBankVersion = 2;
+export const bundledQuestionBankPath = fileURLToPath(import.meta.resolve("@data/question-bank.json.zst"));
+
+export type QuestionBank = {
+  version: typeof questionBankVersion;
+  source: string;
+  updatedAt: string;
+  questions: Question[];
+};
+
+export type QuestionBankStatus = {
+  path: string;
+  exists: boolean;
+  bytes?: number;
+  source?: string;
+  updatedAt?: string;
+  questions?: number;
+};
+
+let defaultBank: Promise<QuestionBank> | undefined;
+const indexes = new WeakMap<QuestionBank, Map<string, Question>>();
+
+export async function loadQuestionBank(path = questionBankCachePath): Promise<QuestionBank> {
+  if (path !== questionBankCachePath) return requireBank(await readQuestionBank(path));
+  defaultBank ??= materializeQuestionBank();
+  return defaultBank;
+}
+
+export async function materializeQuestionBank(
+  cachePath = questionBankCachePath,
+  bundledPath = bundledQuestionBankPath,
+): Promise<QuestionBank> {
+  const cached = await readQuestionBank(cachePath, true);
+  if (cached) return cached;
+  const bundled = requireBank(await readQuestionBank(bundledPath));
+  await saveQuestionBank(bundled, cachePath);
+  return bundled;
+}
+
+export async function readQuestionBank(path: string, replaceable = false): Promise<QuestionBank | undefined> {
+  try {
+    const value = path.endsWith(".zst")
+      ? JSON.parse(new TextDecoder().decode(Bun.zstdDecompressSync(new Uint8Array(await Bun.file(path).arrayBuffer()))))
+      : await Bun.file(path).json();
+    return parseQuestionBank(value);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    if (replaceable && error instanceof UnsupportedBankVersionError) return undefined;
+    throw error;
+  }
+}
+
+export async function saveQuestionBank(bank: QuestionBank, path = questionBankCachePath): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const temporaryPath = `${path}.${process.pid}.tmp`;
+  await Bun.write(temporaryPath, `${JSON.stringify(bank)}\n`);
+  await rename(temporaryPath, path);
+}
+
+export async function questionBankStatus(path = questionBankCachePath): Promise<QuestionBankStatus> {
+  try {
+    const bank = path === questionBankCachePath ? await loadQuestionBank() : await loadQuestionBank(path);
+    return {
+      path,
+      exists: true,
+      bytes: (await stat(path)).size,
+      source: bank.source,
+      updatedAt: bank.updatedAt,
+      questions: bank.questions.length,
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { path, exists: false };
+    throw error;
+  }
+}
+
+export async function findQuestion(id: string): Promise<Question | undefined> {
+  const bank = await loadQuestionBank();
+  let index = indexes.get(bank);
+  if (!index) {
+    index = new Map(bank.questions.map((question) => [question.id, question]));
+    indexes.set(bank, index);
+  }
+  return index.get(id);
+}
+
+export async function nextQuestion(
+  excludedIds: Iterable<string>,
+  focus: Focus,
+  random = Math.random,
+): Promise<Question | undefined> {
+  const excluded = new Set(excludedIds);
+  const bank = await loadQuestionBank();
+  const candidates = bank.questions.filter((question) =>
+    !excluded.has(question.id) &&
+    focus.difficulties.includes(question.difficulty) &&
+    focus.skills.includes(question.skill)
+  );
+  if (candidates.length === 0) return undefined;
+  return candidates[Math.min(candidates.length - 1, Math.floor(random() * candidates.length))];
+}
+
+export function resetQuestionBankMemoryCache(): void {
+  defaultBank = undefined;
+}
+
+function parseQuestionBank(value: unknown): QuestionBank {
+  if (!value || typeof value !== "object") throw new Error("Question bank is not an object.");
+  const bank = value as Partial<QuestionBank>;
+  if (bank.version !== questionBankVersion) throw new UnsupportedBankVersionError(bank.version);
+  if (typeof bank.source !== "string" || !bank.source) throw new Error("Question bank is missing its source.");
+  if (typeof bank.updatedAt !== "string") throw new Error("Question bank has an invalid update timestamp.");
+  if (!Array.isArray(bank.questions)) throw new Error("Question bank is missing questions.");
+  return bank as QuestionBank;
+}
+
+function requireBank(bank: QuestionBank | undefined): QuestionBank {
+  if (!bank) throw new Error("Question bank is missing from the package.");
+  return bank;
+}
+
+class UnsupportedBankVersionError extends Error {
+  constructor(version: unknown) {
+    super(`Question bank version ${String(version)} is not supported.`);
+  }
+}

package/src/questions/practice-sat.ts

@@ -0,0 +1,14 @@
+import { spawn } from "node:child_process";
+import type { Question } from "@/questions/question.ts";
+
+export const practiceSatSite = "https://practicesat.vercel.app";
+
+export function questionPageUrl(question: Question): string {
+  return `${practiceSatSite}/question/${encodeURIComponent(question.id)}`;
+}
+
+export function openQuestionPage(question: Question): void {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  const child = spawn(command, [questionPageUrl(question)], { detached: true, stdio: "ignore" });
+  child.unref();
+}

package/src/questions/question.ts

@@ -0,0 +1,25 @@
+export type Difficulty = "E" | "M" | "H";
+export type DomainCode = "INI" | "CAS" | "EOI" | "SEC";
+export type SkillCode = "CID" | "INF" | "COE" | "WIC" | "TSP" | "CTC" | "SYN" | "TRA" | "BOU" | "FSS";
+
+export type QuestionChoice = {
+  key: string;
+  content: string;
+};
+
+export type Question = {
+  id: string;
+  sourceId: string;
+  difficulty: Difficulty;
+  domain: DomainCode;
+  skill: SkillCode;
+  passage?: string;
+  prompt: string;
+  choices: QuestionChoice[];
+  correctAnswers: string[];
+  explanation?: string;
+};
+
+export function checkAnswer(question: Question, answer: string): boolean {
+  return question.correctAnswers.includes(answer);
+}

package/src/questions/taxonomy.ts

@@ -0,0 +1,56 @@
+import type { Difficulty, DomainCode, SkillCode } from "@/questions/question.ts";
+
+export const difficulties = ["E", "M", "H"] as const satisfies readonly Difficulty[];
+export const domains = ["INI", "CAS", "EOI", "SEC"] as const satisfies readonly DomainCode[];
+export const skills = ["CID", "INF", "COE", "WIC", "TSP", "CTC", "SYN", "TRA", "BOU", "FSS"] as const satisfies readonly SkillCode[];
+
+export const skillsByDomain: Record<DomainCode, readonly SkillCode[]> = {
+  INI: ["CID", "INF", "COE"],
+  CAS: ["WIC", "TSP", "CTC"],
+  EOI: ["SYN", "TRA"],
+  SEC: ["BOU", "FSS"],
+};
+
+export const difficultyLabels: Record<Difficulty, string> = {
+  E: "Easy",
+  M: "Medium",
+  H: "Hard",
+};
+
+export const domainLabels: Record<DomainCode, string> = {
+  INI: "Information and Ideas",
+  CAS: "Craft and Structure",
+  EOI: "Expression of Ideas",
+  SEC: "Standard English Conventions",
+};
+
+export const skillLabels: Record<SkillCode, string> = {
+  CID: "Central Ideas and Details",
+  INF: "Inferences",
+  COE: "Command of Evidence",
+  WIC: "Words in Context",
+  TSP: "Text Structure and Purpose",
+  CTC: "Cross-Text Connections",
+  SYN: "Transitions",
+  TRA: "Rhetorical Synthesis",
+  BOU: "Boundaries",
+  FSS: "Form, Structure, and Sense",
+};
+
+export function isDifficulty(value: unknown): value is Difficulty {
+  return typeof value === "string" && difficulties.includes(value as Difficulty);
+}
+
+export function isDomainCode(value: unknown): value is DomainCode {
+  return typeof value === "string" && domains.includes(value as DomainCode);
+}
+
+export function isSkillCode(value: unknown): value is SkillCode {
+  return typeof value === "string" && skills.includes(value as SkillCode);
+}
+
+export function domainForSkill(skill: SkillCode): DomainCode {
+  const domain = domains.find((candidate) => skillsByDomain[candidate].includes(skill));
+  if (!domain) throw new Error(`Unknown SAT skill: ${skill}`);
+  return domain;
+}

package/src/text/duration.ts

@@ -0,0 +1,4 @@
+export function formatDuration(seconds: number): string {
+  const rounded = Math.max(0, Math.round(seconds));
+  return `${Math.floor(rounded / 60)}:${String(rounded % 60).padStart(2, "0")}`;
+}