@mdsrs/core 0.0.0

package/README.md

@@ -0,0 +1,33 @@
+# @mdsrs/core
+
+Core primitives for Markdown-native spaced repetition.
+
+This package contains:
+
+- `parseDeck` and `parseCollection` for `Q:/A:` and `C:` Markdown cards.
+- `hashCardContent` and `hashCardFamily` for content-addressed card identity.
+- `scheduleReview` for deterministic FSRS-style scheduling.
+- `buildReviewQueue` for due-card ordering and cloze sibling burial.
+- `buildDeckTree` for human-readable deck navigation.
+
+## Example
+
+```ts
+import { buildReviewQueue, parseCollection, scheduleReview } from '@mdsrs/core';
+
+const cards = parseCollection([
+	{
+		deckName: 'Example',
+		filePath: 'example.md',
+		text: 'Q: What is the source of truth?\nA: Markdown.'
+	}
+]);
+
+const queue = buildReviewQueue(cards, new Map());
+const result = scheduleReview(queue[0]?.performance, 'good', new Date('2026-01-01T00:00:00.000Z'));
+```
+
+## Runtime note
+
+`@mdsrs/core` currently uses Node's built-in `crypto` module for synchronous SHA-256 hashing.
+The API is otherwise framework-agnostic and does not depend on a database, renderer, or web framework.

package/dist/deck-tree.d.ts

@@ -0,0 +1,3 @@
+import type { Card, DeckTreeNode } from './types.js';
+export declare const buildDeckTree: (cards: Card[]) => DeckTreeNode[];
+//# sourceMappingURL=deck-tree.d.ts.map

package/dist/deck-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deck-tree.d.ts","sourceRoot":"","sources":["../src/deck-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAyBrD,eAAO,MAAM,aAAa,GAAI,OAAO,IAAI,EAAE,KAAG,YAAY,EAyCzD,CAAC"}

package/dist/deck-tree.js

@@ -0,0 +1,56 @@
+const titleize = (value) => value
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.slice(0, 1).toUpperCase() + part.slice(1))
+    .join(' ');
+const ensureNode = (nodes, path, fallbackName) => {
+    let node = nodes.get(path);
+    if (node)
+        return node;
+    node = {
+        path,
+        name: fallbackName,
+        cardCount: 0,
+        totalCardCount: 0,
+        children: []
+    };
+    nodes.set(path, node);
+    return node;
+};
+export const buildDeckTree = (cards) => {
+    const nodes = new Map();
+    nodes.set('', { path: '', name: 'All', cardCount: 0, totalCardCount: 0, children: [] });
+    for (const card of cards) {
+        const nodePath = card.nodePath;
+        const parts = nodePath.split('/').filter(Boolean);
+        for (let index = 0; index < parts.length; index++) {
+            const path = parts.slice(0, index + 1).join('/');
+            ensureNode(nodes, path, index === parts.length - 1 ? card.displayName : titleize(parts[index] ?? ''));
+        }
+        const node = ensureNode(nodes, nodePath, card.displayName);
+        node.name = card.displayName;
+        node.cardCount += 1;
+        for (let index = 0; index <= parts.length; index++) {
+            const ancestorPath = parts.slice(0, index).join('/');
+            const ancestor = nodes.get(ancestorPath);
+            if (ancestor)
+                ancestor.totalCardCount += 1;
+        }
+    }
+    for (const node of nodes.values()) {
+        node.children = [];
+    }
+    for (const node of nodes.values()) {
+        if (!node.path)
+            continue;
+        const parentPath = node.path.split('/').slice(0, -1).join('/');
+        nodes.get(parentPath)?.children.push(node);
+    }
+    const sortNodes = (items) => {
+        items.sort((left, right) => left.name.localeCompare(right.name));
+        for (const item of items)
+            sortNodes(item.children);
+        return items;
+    };
+    return sortNodes(nodes.get('')?.children ?? []);
+};

package/dist/hash.d.ts

@@ -0,0 +1,5 @@
+import type { CardContent } from './types.js';
+export declare const hashText: (text: string) => string;
+export declare const hashCardContent: (content: CardContent) => string;
+export declare const hashCardFamily: (content: CardContent) => string | null;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,WAAoD,CAAC;AAE1F,eAAO,MAAM,eAAe,GAAI,SAAS,WAAW,WAMnD,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,SAAS,WAAW,kBACkB,CAAC"}

package/dist/hash.js

@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+export const hashText = (text) => createHash('sha256').update(text).digest('hex');
+export const hashCardContent = (content) => {
+    if (content.type === 'basic') {
+        return hashText(`Basic\0${content.question}\0${content.answer}`);
+    }
+    return hashText(`Cloze\0${content.text}\0${content.start}\0${content.end}`);
+};
+export const hashCardFamily = (content) => content.type === 'cloze' ? hashText(`Cloze\0${content.text}`) : null;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './deck-tree.js';
+export * from './hash.js';
+export * from './parse.js';
+export * from './queue.js';
+export * from './render.js';
+export * from './schedule.js';
+export * from './stats.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './deck-tree.js';
+export * from './hash.js';
+export * from './parse.js';
+export * from './queue.js';
+export * from './render.js';
+export * from './schedule.js';
+export * from './stats.js';
+export * from './types.js';

package/dist/parse.d.ts

@@ -0,0 +1,9 @@
+import type { Card, DeckSource } from './types.js';
+export declare class MdsrsParseError extends Error {
+    readonly filePath: string;
+    readonly line: number;
+    constructor(message: string, filePath: string, line: number);
+}
+export declare const parseDeck: (source: DeckSource) => Card[];
+export declare const parseCollection: (sources: DeckSource[]) => Card[];
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAe,UAAU,EAAE,MAAM,YAAY,CAAC;AAEhE,qBAAa,eAAgB,SAAQ,KAAK;IAGxC,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAFrB,OAAO,EAAE,MAAM,EACN,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM;CAItB;AA6BD,eAAO,MAAM,SAAS,GAAI,QAAQ,UAAU,KAAG,IAAI,EAiGlD,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,SAAS,UAAU,EAAE,WAA4C,CAAC"}

package/dist/parse.js

@@ -0,0 +1,166 @@
+import { hashCardContent, hashCardFamily } from './hash.js';
+import { renderBackMarkdown, renderFrontMarkdown } from './render.js';
+export class MdsrsParseError extends Error {
+    filePath;
+    line;
+    constructor(message, filePath, line) {
+        super(`${message} Location: ${filePath}:${line + 1}`);
+        this.filePath = filePath;
+        this.line = line;
+    }
+}
+const defaultNodePath = (filePath) => {
+    const parts = filePath.replace(/\.md$/, '').split('/').filter(Boolean);
+    return (parts.at(-1) === 'index' ? parts.slice(0, -1) : parts).join('/');
+};
+const lineKind = (line) => {
+    if (line.startsWith('Q:'))
+        return ['question', line.slice(2).trim()];
+    if (line.startsWith('A:'))
+        return ['answer', line.slice(2).trim()];
+    if (line.startsWith('C:'))
+        return ['cloze', line.slice(2).trim()];
+    if (line.trim() === '---')
+        return ['separator', ''];
+    return ['text', line];
+};
+const makeCard = (source, range, content) => ({
+    hash: hashCardContent(content),
+    familyHash: hashCardFamily(content),
+    deckName: source.deckName,
+    filePath: source.filePath,
+    folderPath: source.folderPath ?? '',
+    nodePath: source.nodePath ?? defaultNodePath(source.filePath),
+    displayName: source.displayName ?? source.deckName,
+    range,
+    content,
+    frontMarkdown: renderFrontMarkdown(content),
+    backMarkdown: renderBackMarkdown(content)
+});
+export const parseDeck = (source) => {
+    const cards = [];
+    let state = { type: 'start' };
+    const lines = source.text.split(/\r?\n/);
+    const finishBasic = (line, question, answer, startLine) => {
+        cards.push(makeCard(source, [startLine, line], {
+            type: 'basic',
+            question: question.trim(),
+            answer: answer.trim()
+        }));
+    };
+    const finishCloze = (line, text, startLine) => {
+        cards.push(...parseClozeCards(source, [startLine, line], text));
+    };
+    for (const [lineNumber, rawLine] of lines.entries()) {
+        const [kind, text] = lineKind(rawLine);
+        if (state.type === 'start') {
+            if (kind === 'question')
+                state = { type: 'question', question: text, startLine: lineNumber };
+            else if (kind === 'answer')
+                throw new MdsrsParseError('Found answer tag without a question.', source.filePath, lineNumber);
+            else if (kind === 'cloze')
+                state = { type: 'cloze', text, startLine: lineNumber };
+            continue;
+        }
+        if (state.type === 'question') {
+            if (kind === 'answer')
+                state = {
+                    type: 'answer',
+                    question: state.question,
+                    answer: text,
+                    startLine: state.startLine
+                };
+            else if (kind === 'text')
+                state = { ...state, question: `${state.question}\n${text}` };
+            else if (kind === 'question')
+                throw new MdsrsParseError('New question without answer.', source.filePath, lineNumber);
+            else
+                throw new MdsrsParseError('Found invalid tag while reading a question.', source.filePath, lineNumber);
+            continue;
+        }
+        if (state.type === 'answer') {
+            if (kind === 'text')
+                state = { ...state, answer: `${state.answer}\n${text}` };
+            else {
+                finishBasic(lineNumber, state.question, state.answer, state.startLine);
+                if (kind === 'question')
+                    state = { type: 'question', question: text, startLine: lineNumber };
+                else if (kind === 'cloze')
+                    state = { type: 'cloze', text, startLine: lineNumber };
+                else if (kind === 'separator')
+                    state = { type: 'start' };
+                else
+                    throw new MdsrsParseError('Found answer tag while reading an answer.', source.filePath, lineNumber);
+            }
+            continue;
+        }
+        if (kind === 'text')
+            state = { ...state, text: `${state.text}\n${text}` };
+        else {
+            finishCloze(lineNumber, state.text, state.startLine);
+            if (kind === 'question')
+                state = { type: 'question', question: text, startLine: lineNumber };
+            else if (kind === 'cloze')
+                state = { type: 'cloze', text, startLine: lineNumber };
+            else if (kind === 'separator')
+                state = { type: 'start' };
+            else
+                throw new MdsrsParseError('Found answer tag while reading a cloze card.', source.filePath, lineNumber);
+        }
+    }
+    const lastLine = Math.max(lines.length - 1, 0);
+    if (state.type === 'question') {
+        throw new MdsrsParseError('File ended while reading a question without an answer.', source.filePath, lastLine);
+    }
+    if (state.type === 'answer')
+        finishBasic(lastLine, state.question, state.answer, state.startLine);
+    if (state.type === 'cloze')
+        finishCloze(lastLine, state.text, state.startLine);
+    return uniqueCards(cards);
+};
+export const parseCollection = (sources) => uniqueCards(sources.flatMap(parseDeck));
+const uniqueCards = (cards) => {
+    const seen = new Set();
+    return cards
+        .filter((card) => {
+        if (seen.has(card.hash))
+            return false;
+        seen.add(card.hash);
+        return true;
+    })
+        .sort((left, right) => left.hash.localeCompare(right.hash));
+};
+const parseClozeCards = (source, range, rawText) => {
+    const text = rawText.trim();
+    let cleanText = '';
+    let open = null;
+    const ranges = [];
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        const previous = text[index - 1];
+        const next = text[index + 1];
+        const isImageBracket = char === '[' && previous === '!';
+        const isEscapedBracket = (char === '[' || char === ']') && previous === '\\';
+        if (char === '\\' && (next === '[' || next === ']'))
+            continue;
+        if (char === '[' && !isImageBracket && !isEscapedBracket) {
+            open = cleanText.length;
+            continue;
+        }
+        if (char === ']' && open !== null && !isEscapedBracket) {
+            ranges.push([open, cleanText.length - 1]);
+            open = null;
+            continue;
+        }
+        cleanText += char;
+    }
+    if (ranges.length === 0) {
+        throw new MdsrsParseError('Cloze card must contain at least one cloze deletion.', source.filePath, range[0]);
+    }
+    return ranges.map(([start, end]) => makeCard(source, range, {
+        type: 'cloze',
+        text: cleanText,
+        start,
+        end
+    }));
+};

package/dist/queue.d.ts

@@ -0,0 +1,9 @@
+import type { Card, CardPerformance, ReviewQueueItem } from './types.js';
+export interface BuildReviewQueueOptions {
+    now?: Date;
+    limit?: number;
+    burySiblings?: boolean;
+    deckName?: string;
+}
+export declare const buildReviewQueue: (cards: Card[], performances: ReadonlyMap<string, CardPerformance>, options?: BuildReviewQueueOptions) => ReviewQueueItem[];
+//# sourceMappingURL=queue.d.ts.map

package/dist/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEzE,MAAM,WAAW,uBAAuB;IACvC,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,gBAAgB,GAC5B,OAAO,IAAI,EAAE,EACb,cAAc,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,EAClD,UAAS,uBAA4B,KACnC,eAAe,EAsBjB,CAAC"}

package/dist/queue.js

@@ -0,0 +1,38 @@
+import { isDue, toDateString } from './schedule.js';
+export const buildReviewQueue = (cards, performances, options = {}) => {
+    const now = options.now ?? new Date();
+    const seenFamilies = new Set();
+    const today = toDateString(now);
+    const dueCards = cards
+        .filter((card) => options.deckName == null || card.deckName === options.deckName)
+        .map((card) => ({ card, performance: performances.get(card.hash) ?? null }))
+        .filter((item) => isDue(item.performance, now))
+        .sort(compareQueueItems(today));
+    const queue = [];
+    for (const item of dueCards) {
+        const familyHash = item.card.familyHash;
+        if (options.burySiblings !== false && familyHash) {
+            if (seenFamilies.has(familyHash))
+                continue;
+            seenFamilies.add(familyHash);
+        }
+        queue.push(item);
+        if (options.limit != null && queue.length >= options.limit)
+            break;
+    }
+    return queue;
+};
+const compareQueueItems = (today) => (left, right) => {
+    const leftDue = left.performance?.dueDate ?? '';
+    const rightDue = right.performance?.dueDate ?? '';
+    if (leftDue !== rightDue)
+        return leftDue.localeCompare(rightDue);
+    if ((left.performance?.reviewCount ?? 0) !== (right.performance?.reviewCount ?? 0)) {
+        return (left.performance?.reviewCount ?? 0) - (right.performance?.reviewCount ?? 0);
+    }
+    if ((left.performance?.dueDate == null ? today : left.performance.dueDate) !==
+        (right.performance?.dueDate == null ? today : right.performance.dueDate)) {
+        return (left.performance?.dueDate ?? today).localeCompare(right.performance?.dueDate ?? today);
+    }
+    return left.card.hash.localeCompare(right.card.hash);
+};

package/dist/render.d.ts

@@ -0,0 +1,4 @@
+import type { CardContent } from './types.js';
+export declare const renderFrontMarkdown: (content: CardContent) => string;
+export declare const renderBackMarkdown: (content: CardContent) => string;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,eAAO,MAAM,mBAAmB,GAAI,SAAS,WAAW,WAGvD,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,SAAS,WAAW,WAItD,CAAC"}

package/dist/render.js

@@ -0,0 +1,30 @@
+export const renderFrontMarkdown = (content) => {
+    if (content.type === 'basic')
+        return content.question;
+    return `${content.text.slice(0, content.start)}[...]${content.text.slice(content.end + 1)}`;
+};
+export const renderBackMarkdown = (content) => {
+    if (content.type === 'basic')
+        return content.answer;
+    if (isInsideInlineMath(content.text, content.start, content.end))
+        return content.text;
+    return `${content.text.slice(0, content.start)}**${content.text.slice(content.start, content.end + 1)}**${content.text.slice(content.end + 1)}`;
+};
+const isInsideInlineMath = (text, start, end) => {
+    let inMath = false;
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        const previous = text[index - 1];
+        if (char !== '$' || previous === '\\')
+            continue;
+        if (!inMath && index < start) {
+            inMath = true;
+            continue;
+        }
+        if (inMath && index > end)
+            return true;
+        if (inMath)
+            inMath = false;
+    }
+    return false;
+};

package/dist/schedule.d.ts

@@ -0,0 +1,12 @@
+import type { CardPerformance, Grade, ReviewResult } from './types.js';
+export declare const retrievability: (intervalDays: number, stability: number) => number;
+export declare const interval: (recall: number, stability: number) => number;
+export declare const initialStability: (grade: Grade) => 0.40255 | 1.18385 | 3.173 | 15.69105;
+export declare const initialDifficulty: (grade: Grade) => number;
+export declare const newDifficulty: (difficulty: number, grade: Grade) => number;
+export declare const newStability: (difficulty: number, stability: number, recall: number, grade: Grade) => number;
+export declare const scheduleReview: (performance: CardPerformance | null | undefined, grade: Grade, reviewedAt?: Date) => ReviewResult;
+export declare const toTimestamp: (date: Date) => string;
+export declare const toDateString: (date: Date) => string;
+export declare const isDue: (performance: Pick<CardPerformance, "dueDate"> | null | undefined, now?: Date) => boolean;
+//# sourceMappingURL=schedule.d.ts.map

package/dist/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../src/schedule.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAqBvE,eAAO,MAAM,cAAc,GAAI,cAAc,MAAM,EAAE,WAAW,MAAM,WACnB,CAAC;AAEpD,eAAO,MAAM,QAAQ,GAAI,QAAQ,MAAM,EAAE,WAAW,MAAM,WACP,CAAC;AAEpD,eAAO,MAAM,gBAAgB,GAAI,OAAO,KAAK,yCAMnC,CAAC;AAEX,eAAO,MAAM,iBAAiB,GAAI,OAAO,KAAK,WACmC,CAAC;AAOlF,eAAO,MAAM,aAAa,GAAI,YAAY,MAAM,EAAE,OAAO,KAAK,WAG5D,CAAC;AAyBH,eAAO,MAAM,YAAY,GACxB,YAAY,MAAM,EAClB,WAAW,MAAM,EACjB,QAAQ,MAAM,EACd,OAAO,KAAK,WAI6C,CAAC;AAE3D,eAAO,MAAM,cAAc,GAC1B,aAAa,eAAe,GAAG,IAAI,GAAG,SAAS,EAC/C,OAAO,KAAK,EACZ,iBAAuB,KACrB,YA6BF,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,MAAM,IAAI,WAAuB,CAAC;AAE9D,eAAO,MAAM,YAAY,GAAI,MAAM,IAAI,WAAoC,CAAC;AAE5E,eAAO,MAAM,KAAK,GACjB,aAAa,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,EAChE,UAAgB,YAC4D,CAAC"}

package/dist/schedule.js

@@ -0,0 +1,75 @@
+const weights = [
+    0.40255, 1.18385, 3.173, 15.69105, 7.1949, 0.5345, 1.4604, 0.0046, 1.54575, 0.1192, 1.01925,
+    1.9395, 0.11, 0.29605, 2.2698, 0.2315, 2.9898, 0.51655, 0.6621
+];
+const desiredRecall = 0.9;
+const factor = 19 / 81;
+const decay = -0.5;
+const gradeValue = (grade) => ({
+    forgot: 1,
+    hard: 2,
+    good: 3,
+    easy: 4
+})[grade];
+const clampDifficulty = (difficulty) => Math.min(10, Math.max(1, difficulty));
+export const retrievability = (intervalDays, stability) => (1 + factor * (intervalDays / stability)) ** decay;
+export const interval = (recall, stability) => (stability / factor) * (recall ** (1 / decay) - 1);
+export const initialStability = (grade) => ({
+    forgot: weights[0],
+    hard: weights[1],
+    good: weights[2],
+    easy: weights[3]
+})[grade];
+export const initialDifficulty = (grade) => clampDifficulty(weights[4] - Math.exp(weights[5] * (gradeValue(grade) - 1)) + 1);
+const deltaDifficulty = (grade) => -weights[6] * (gradeValue(grade) - 3);
+const difficultyPrime = (difficulty, grade) => difficulty + deltaDifficulty(grade) * ((10 - difficulty) / 9);
+export const newDifficulty = (difficulty, grade) => clampDifficulty(weights[7] * initialDifficulty('easy') + (1 - weights[7]) * difficultyPrime(difficulty, grade));
+const successStability = (difficulty, stability, recall, grade) => {
+    const hardPenalty = grade === 'hard' ? weights[15] : 1;
+    const easyBonus = grade === 'easy' ? weights[16] : 1;
+    const alpha = 1 +
+        (11 - difficulty) *
+            stability ** -weights[9] *
+            (Math.exp(weights[10] * (1 - recall)) - 1) *
+            hardPenalty *
+            easyBonus *
+            Math.exp(weights[8]);
+    return stability * alpha;
+};
+const failStability = (difficulty, stability, recall) => Math.min(difficulty ** -weights[12] *
+    ((stability + 1) ** weights[13] - 1) *
+    Math.exp(weights[14] * (1 - recall)) *
+    weights[11], stability);
+export const newStability = (difficulty, stability, recall, grade) => grade === 'forgot'
+    ? failStability(difficulty, stability, recall)
+    : successStability(difficulty, stability, recall, grade);
+export const scheduleReview = (performance, grade, reviewedAt = new Date()) => {
+    const previousInterval = performance?.intervalDays ?? 0;
+    const previousStability = performance?.stability;
+    const previousDifficulty = performance?.difficulty;
+    const stability = previousStability == null || previousDifficulty == null
+        ? initialStability(grade)
+        : newStability(previousDifficulty, previousStability, retrievability(Math.max(previousInterval, 1), previousStability), grade);
+    const difficulty = previousDifficulty == null ? initialDifficulty(grade) : newDifficulty(previousDifficulty, grade);
+    const intervalRaw = interval(desiredRecall, stability);
+    const intervalDays = Math.max(Math.round(intervalRaw), 1);
+    const dueDate = addDays(reviewedAt, intervalDays);
+    return {
+        lastReviewedAt: toTimestamp(reviewedAt),
+        stability,
+        difficulty,
+        intervalRaw,
+        intervalDays,
+        dueDate,
+        reviewCount: (performance?.reviewCount ?? 0) + 1,
+        grade
+    };
+};
+export const toTimestamp = (date) => date.toISOString();
+export const toDateString = (date) => date.toISOString().slice(0, 10);
+export const isDue = (performance, now = new Date()) => performance?.dueDate == null || performance.dueDate <= toDateString(now);
+const addDays = (date, days) => {
+    const next = new Date(date);
+    next.setUTCDate(next.getUTCDate() + days);
+    return toDateString(next);
+};

package/dist/stats.d.ts

@@ -0,0 +1,48 @@
+import type { Card, DeckTreeNode, Grade } from './types.js';
+export interface CollectionCardState {
+    cardHash: string;
+    active?: boolean;
+    addedAt?: Date | string | null;
+    dueDate: string | null;
+    reviewCount?: number;
+}
+export interface CollectionReviewState {
+    cardHash: string;
+    reviewedAt: Date | string;
+    grade: Grade | string;
+}
+export interface DeckStats {
+    path: string;
+    name: string;
+    cardCount: number;
+    totalCardCount: number;
+    activeCards: number;
+    dueCards: number;
+    queuedCards: number;
+    overdueCards: number;
+    newCards: number;
+    cardsAddedLast7Days: number;
+    reviewsLast7Days: number;
+    hitRateLast30Days: number | null;
+    children: DeckStats[];
+}
+export interface CollectionStats {
+    totalCards: number;
+    activeCards: number;
+    dueCards: number;
+    queuedCards: number;
+    overdueCards: number;
+    newCards: number;
+    cardsAddedLast7Days: number;
+    reviewsToday: number;
+    reviewsLast7Days: number;
+    reviewActiveDaysLast14: number;
+    hitRateLast30Days: number | null;
+    daysSinceLastReview: number | null;
+    decks: DeckStats[];
+}
+export interface BuildCollectionStatsOptions {
+    now?: Date;
+}
+export declare const buildCollectionStats: (cards: Card[], deckTree: DeckTreeNode[], cardStates: CollectionCardState[], reviews: CollectionReviewState[], options?: BuildCollectionStatsOptions) => CollectionStats;
+//# sourceMappingURL=stats.d.ts.map

package/dist/stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../src/stats.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAmB,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAE7E,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,IAAI,GAAG,MAAM,CAAC;IAC1B,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,EAAE,SAAS,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,KAAK,EAAE,SAAS,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,2BAA2B;IAC3C,GAAG,CAAC,EAAE,IAAI,CAAC;CACX;AAkBD,eAAO,MAAM,oBAAoB,GAChC,OAAO,IAAI,EAAE,EACb,UAAU,YAAY,EAAE,EACxB,YAAY,mBAAmB,EAAE,EACjC,SAAS,qBAAqB,EAAE,EAChC,UAAS,2BAAgC,KACvC,eAmDF,CAAC"}

package/dist/stats.js

@@ -0,0 +1,126 @@
+import { toDateString } from './schedule.js';
+import { buildReviewQueue } from './queue.js';
+const dayMs = 24 * 60 * 60 * 1000;
+const startOfDay = (date) => new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+const toDate = (value) => (value instanceof Date ? value : new Date(value));
+const daysBetween = (left, right) => Math.max(0, Math.floor((startOfDay(left).getTime() - startOfDay(right).getTime()) / dayMs));
+const hitRate = (reviews) => {
+    if (reviews.length === 0)
+        return null;
+    const hits = reviews.filter((review) => review.grade !== 'forgot').length;
+    return hits / reviews.length;
+};
+export const buildCollectionStats = (cards, deckTree, cardStates, reviews, options = {}) => {
+    const now = options.now ?? new Date();
+    const today = toDateString(now);
+    const sevenDaysAgo = new Date(now.getTime() - 7 * dayMs);
+    const fourteenDaysAgo = new Date(now.getTime() - 14 * dayMs);
+    const thirtyDaysAgo = new Date(now.getTime() - 30 * dayMs);
+    const cardStateByHash = new Map(cardStates.map((card) => [card.cardHash, card]));
+    const hasCardStates = cardStateByHash.size > 0;
+    const activeCards = cards.filter((card) => isActiveCard(card, cardStateByHash, hasCardStates));
+    const activeCardHashes = new Set(activeCards.map((card) => card.hash));
+    const dueCards = activeCards.filter((card) => isDueCard(card, cardStateByHash, hasCardStates, today));
+    const performances = cardStatePerformances(activeCards, cardStateByHash);
+    const queuedCards = buildReviewQueue(activeCards, performances, { now });
+    const overdueCards = activeCards.filter((card) => isOverdueCard(card, cardStateByHash, today));
+    const newCards = activeCards.filter((card) => isNewCard(card, cardStateByHash, hasCardStates));
+    const cardsAddedLast7Days = activeCards.filter((card) => wasAddedSince(card, cardStateByHash, hasCardStates, sevenDaysAgo));
+    const activeReviews = reviews.filter((review) => activeCardHashes.has(review.cardHash));
+    const reviewsToday = activeReviews.filter((review) => toDate(review.reviewedAt).toISOString().slice(0, 10) === today);
+    const reviewsLast7Days = activeReviews.filter((review) => toDate(review.reviewedAt) >= sevenDaysAgo);
+    const reviewsLast14Days = activeReviews.filter((review) => toDate(review.reviewedAt) >= fourteenDaysAgo);
+    const reviewsLast30Days = activeReviews.filter((review) => toDate(review.reviewedAt) >= thirtyDaysAgo);
+    const activeDays = new Set(reviewsLast14Days.map((review) => toDate(review.reviewedAt).toISOString().slice(0, 10)));
+    const lastReview = activeReviews
+        .map((review) => toDate(review.reviewedAt))
+        .sort((left, right) => right.getTime() - left.getTime())[0];
+    return {
+        totalCards: cards.length,
+        activeCards: activeCards.length,
+        dueCards: dueCards.length,
+        queuedCards: queuedCards.length,
+        overdueCards: overdueCards.length,
+        newCards: newCards.length,
+        cardsAddedLast7Days: cardsAddedLast7Days.length,
+        reviewsToday: reviewsToday.length,
+        reviewsLast7Days: reviewsLast7Days.length,
+        reviewActiveDaysLast14: activeDays.size,
+        hitRateLast30Days: hitRate(reviewsLast30Days),
+        daysSinceLastReview: lastReview ? daysBetween(now, lastReview) : null,
+        decks: buildDeckStats(deckTree, cards, cardStateByHash, activeReviews, hasCardStates, now)
+    };
+};
+const isActiveCard = (card, cardStateByHash, hasCardStates) => {
+    if (!hasCardStates)
+        return true;
+    return cardStateByHash.get(card.hash)?.active !== false && cardStateByHash.has(card.hash);
+};
+const isDueCard = (card, cardStateByHash, hasCardStates, today) => {
+    if (!hasCardStates)
+        return true;
+    const dueDate = cardStateByHash.get(card.hash)?.dueDate;
+    return dueDate == null || dueDate <= today;
+};
+const isOverdueCard = (card, cardStateByHash, today) => {
+    const dueDate = cardStateByHash.get(card.hash)?.dueDate;
+    return dueDate != null && dueDate < today;
+};
+const isNewCard = (card, cardStateByHash, hasCardStates) => !hasCardStates || cardStateByHash.get(card.hash)?.dueDate == null;
+const wasAddedSince = (card, cardStateByHash, hasCardStates, since) => {
+    if (!hasCardStates)
+        return true;
+    const addedAt = cardStateByHash.get(card.hash)?.addedAt;
+    return addedAt ? toDate(addedAt) >= since : false;
+};
+const cardStatePerformances = (cards, cardStateByHash) => new Map(cards.map((card) => {
+    const state = cardStateByHash.get(card.hash);
+    return [
+        card.hash,
+        {
+            lastReviewedAt: null,
+            stability: null,
+            difficulty: null,
+            intervalRaw: null,
+            intervalDays: null,
+            dueDate: state?.dueDate ?? null,
+            reviewCount: state?.reviewCount ?? 0
+        }
+    ];
+}));
+const nodeCardsForStats = (cards, node) => cards.filter((card) => card.nodePath === node.path || card.nodePath.startsWith(`${node.path}/`));
+const buildDeckStats = (nodes, cards, cardStateByHash, reviews, hasCardStates, now) => {
+    const today = toDateString(now);
+    const sevenDaysAgo = new Date(now.getTime() - 7 * dayMs);
+    const thirtyDaysAgo = new Date(now.getTime() - 30 * dayMs);
+    const reviewsByCard = new Map();
+    for (const review of reviews) {
+        const cardReviews = reviewsByCard.get(review.cardHash) ?? [];
+        cardReviews.push(review);
+        reviewsByCard.set(review.cardHash, cardReviews);
+    }
+    return nodes.map((node) => {
+        const nodeCards = nodeCardsForStats(cards, node);
+        const activeCards = nodeCards.filter((card) => isActiveCard(card, cardStateByHash, hasCardStates));
+        const performances = cardStatePerformances(activeCards, cardStateByHash);
+        const nodeReviews = activeCards.flatMap((card) => reviewsByCard.get(card.hash) ?? []);
+        const reviewsLast30Days = nodeReviews.filter((review) => toDate(review.reviewedAt) >= thirtyDaysAgo);
+        return {
+            path: node.path,
+            name: node.name,
+            cardCount: node.cardCount,
+            totalCardCount: node.totalCardCount,
+            activeCards: activeCards.length,
+            dueCards: activeCards.filter((card) => isDueCard(card, cardStateByHash, hasCardStates, today))
+                .length,
+            queuedCards: buildReviewQueue(activeCards, performances, { now }).length,
+            overdueCards: activeCards.filter((card) => isOverdueCard(card, cardStateByHash, today)).length,
+            newCards: activeCards.filter((card) => isNewCard(card, cardStateByHash, hasCardStates)).length,
+            cardsAddedLast7Days: activeCards.filter((card) => wasAddedSince(card, cardStateByHash, hasCardStates, sevenDaysAgo)).length,
+            reviewsLast7Days: nodeReviews.filter((review) => toDate(review.reviewedAt) >= sevenDaysAgo)
+                .length,
+            hitRateLast30Days: hitRate(reviewsLast30Days),
+            children: buildDeckStats(node.children, cards, cardStateByHash, reviews, hasCardStates, now)
+        };
+    });
+};

package/dist/types.d.ts

@@ -0,0 +1,63 @@
+export type Grade = 'forgot' | 'hard' | 'good' | 'easy';
+export type CardContent = {
+    type: 'basic';
+    question: string;
+    answer: string;
+} | {
+    type: 'cloze';
+    text: string;
+    start: number;
+    end: number;
+};
+export interface DeckSource {
+    deckName: string;
+    filePath: string;
+    text: string;
+    folderPath?: string;
+    nodePath?: string;
+    displayName?: string;
+}
+export interface Card {
+    hash: string;
+    familyHash: string | null;
+    deckName: string;
+    filePath: string;
+    folderPath: string;
+    nodePath: string;
+    displayName: string;
+    range: [number, number];
+    content: CardContent;
+    frontMarkdown: string;
+    backMarkdown: string;
+}
+export interface DeckTreeNode {
+    path: string;
+    name: string;
+    cardCount: number;
+    totalCardCount: number;
+    children: DeckTreeNode[];
+}
+export interface CardPerformance {
+    lastReviewedAt: string | null;
+    stability: number | null;
+    difficulty: number | null;
+    intervalRaw: number | null;
+    intervalDays: number | null;
+    dueDate: string | null;
+    reviewCount: number;
+}
+export interface ReviewResult {
+    lastReviewedAt: string;
+    grade: Grade;
+    stability: number;
+    difficulty: number;
+    intervalRaw: number;
+    intervalDays: number;
+    dueDate: string;
+    reviewCount: number;
+}
+export interface ReviewQueueItem {
+    card: Card;
+    performance: CardPerformance | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAExD,MAAM,MAAM,WAAW,GACpB;IACA,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CACd,GACD;IACA,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACX,CAAC;AAEL,MAAM,WAAW,UAAU;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,IAAI;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxB,OAAO,EAAE,WAAW,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC/B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,IAAI,CAAC;IACX,WAAW,EAAE,eAAe,GAAG,IAAI,CAAC;CACpC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@mdsrs/core",
+  "version": "0.0.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}