@lapis-notes/lapis-plugin-docs 0.0.0-stage → 0.2.0

package/dist/model/markdown.d.ts

@@ -0,0 +1,167 @@
+import { type DocsNote, type DocsRevisionBlock } from "./types";
+export { assertDocsId, createDocsNote, createDocsCodingExercise, isValidDocsId, normalizeDocsBlock, normalizeDocsCodingExercise, normalizeDocsCard, parseDocsNoteMarkdownFile, slugifyDocsId, } from "./markdown-normalize";
+export declare function docsNoteToFrontmatter(note: DocsNote): Partial<{
+    schemaVersion: string;
+    id: string;
+    title: string;
+    docType: import("./types").DocsDocType;
+    summary: string;
+    learningGoal: string;
+    aliases: string[];
+    tags: string[];
+    book: {
+        chapters: {
+            noteId: string;
+        }[];
+    } | undefined;
+    bookId: string | undefined;
+    completedAt: string | undefined;
+    createdAt: string;
+    updatedAt: string;
+    blocks: (Partial<{
+        id: string;
+        type: "concept";
+        title: string | undefined;
+        summary: string;
+        keyPoints: string[];
+        details: string;
+    }> | Partial<{
+        id: string;
+        type: "procedure";
+        title: string | undefined;
+        steps: string[];
+        notes: string;
+    }> | Partial<{
+        id: string;
+        type: "prompt";
+        title: string | undefined;
+        problem: string;
+        requirements: string[];
+        approach: string;
+        traps: string[];
+        tests: string[];
+        answer: string;
+    }> | Partial<{
+        id: string;
+        type: "code";
+        title: string | undefined;
+        language: string;
+        code: string;
+        caption: string;
+    }> | Partial<{
+        id: string;
+        type: "table";
+        title: string | undefined;
+        columns: string[];
+        rows: string[][];
+    }> | Partial<{
+        id: string;
+        type: "story";
+        title: string | undefined;
+        useFor: string[];
+        situation: string;
+        task: string;
+        action: string;
+        result: string;
+        metrics: string[];
+    }> | Partial<{
+        id: string;
+        type: "resources";
+        title: string | undefined;
+        items: Partial<{
+            title: string;
+            url: string;
+            kind: string;
+            notes: string;
+        }>[];
+    }> | Partial<{
+        id: string;
+        type: string;
+        title: string | undefined;
+        body: string;
+    }>)[];
+    cards: Partial<{
+        exercise: Partial<{
+            id: string;
+            difficulty: import("./types").DocsCodingDifficulty;
+            description: string;
+            constraints: string[];
+            signature: {
+                className: string;
+                methodName: string;
+                parameters: {
+                    name: string;
+                    type: import("./types").DocsCodingValueType;
+                }[];
+                returnType: import("./types").DocsCodingValueType;
+            };
+            languages: {
+                language: import("./types").DocsCodingLanguage;
+                version: string;
+                fileName: string;
+                starterCode: string;
+            }[];
+            examples: Partial<{
+                id: string;
+                title: string | undefined;
+                arguments: import("./types").DocsCodingLiteral[];
+                expected: import("./types").DocsCodingLiteral;
+                explanation: string | undefined;
+            }>[];
+            hints: {
+                id: string;
+                title: string;
+                body: string;
+            }[];
+            solutions: Partial<{
+                language: import("./types").DocsCodingLanguage;
+                explanation: string | undefined;
+                code: string;
+            }>[];
+        }>;
+        id: string;
+        type: import("./types").DocsCardType;
+        status: import("./types").DocsCardStatus;
+        prompt: string;
+        answer: string;
+        tags: string[];
+        blockRefs: string[];
+    } | {
+        fsrs: Partial<{
+            due: string;
+            stability: number;
+            difficulty: number;
+            elapsedDays: number;
+            scheduledDays: number;
+            learningSteps: number;
+            reps: number;
+            lapses: number;
+            state: import("./types").DocsFsrsStateName;
+            lastReview: string | undefined;
+        }> | undefined;
+        reviews: Partial<{
+            id: string;
+            rating: import("./types").DocsReviewRating;
+            reviewedAt: string;
+            state: import("./types").DocsFsrsStateName;
+            due: string;
+            stability: number;
+            difficulty: number;
+            elapsedDays: number;
+            scheduledDays: number;
+            learningSteps: number;
+        }>[];
+        id: string;
+        type: import("./types").DocsCardType;
+        status: import("./types").DocsCardStatus;
+        prompt: string;
+        answer: string;
+        tags: string[];
+        blockRefs: string[];
+    }>[];
+}>;
+export declare function docsNoteToMarkdown(note: DocsNote): string;
+export declare function renderDocsBlockMarkdown(block: DocsRevisionBlock, headingLevel?: number): string;
+export declare function renderDocsNoteMarkdown(note: DocsNote, options?: {
+    mode?: "document" | "slides";
+}): string;

package/dist/model/markdown.js

@@ -0,0 +1,365 @@
+import YAML from "yaml";
+import { DOCS_NOTE_SCHEMA_VERSION, } from "./types";
+import { assertDocsId, compactObject } from "./markdown-normalize";
+export { assertDocsId, createDocsNote, createDocsCodingExercise, isValidDocsId, normalizeDocsBlock, normalizeDocsCodingExercise, normalizeDocsCard, parseDocsNoteMarkdownFile, slugifyDocsId, } from "./markdown-normalize";
+function serializeFsrs(fsrsState) {
+    if (!fsrsState)
+        return undefined;
+    return compactObject({
+        due: fsrsState.due,
+        stability: fsrsState.stability,
+        difficulty: fsrsState.difficulty,
+        elapsedDays: fsrsState.elapsedDays,
+        scheduledDays: fsrsState.scheduledDays,
+        learningSteps: fsrsState.learningSteps,
+        reps: fsrsState.reps,
+        lapses: fsrsState.lapses,
+        state: fsrsState.state,
+        lastReview: fsrsState.lastReview,
+    });
+}
+function serializeReviews(reviews) {
+    return reviews.map((review) => compactObject({
+        id: review.id,
+        rating: review.rating,
+        reviewedAt: review.reviewedAt,
+        state: review.state,
+        due: review.due,
+        stability: review.stability,
+        difficulty: review.difficulty,
+        elapsedDays: review.elapsedDays,
+        scheduledDays: review.scheduledDays,
+        learningSteps: review.learningSteps,
+    }));
+}
+function serializeBook(book) {
+    if (!book)
+        return undefined;
+    return {
+        chapters: book.chapters.map((chapter) => ({
+            noteId: assertDocsId(chapter.noteId),
+        })),
+    };
+}
+function serializeBlock(block) {
+    switch (block.type) {
+        case "concept":
+            return compactObject({
+                id: block.id,
+                type: block.type,
+                title: block.title,
+                summary: block.summary,
+                keyPoints: block.keyPoints,
+                details: block.details,
+            });
+        case "procedure":
+            return compactObject({
+                id: block.id,
+                type: block.type,
+                title: block.title,
+                steps: block.steps,
+                notes: block.notes,
+            });
+        case "prompt":
+            return compactObject({
+                id: block.id,
+                type: block.type,
+                title: block.title,
+                problem: block.problem,
+                requirements: block.requirements,
+                approach: block.approach,
+                traps: block.traps,
+                tests: block.tests,
+                answer: block.answer,
+            });
+        case "code":
+            return compactObject({
+                id: block.id,
+                type: block.type,
+                title: block.title,
+                language: block.language,
+                code: block.code,
+                caption: block.caption,
+            });
+        case "table":
+            return compactObject({
+                id: block.id,
+                type: block.type,
+                title: block.title,
+                columns: block.columns,
+                rows: block.rows,
+            });
+        case "callout":
+            return compactObject({
+                id: block.id,
+                type: block.type,
+                title: block.title,
+                tone: block.tone,
+                body: block.body,
+            });
+        case "story":
+            return compactObject({
+                id: block.id,
+                type: block.type,
+                title: block.title,
+                useFor: block.useFor,
+                situation: block.situation,
+                task: block.task,
+                action: block.action,
+                result: block.result,
+                metrics: block.metrics,
+            });
+        case "resources":
+            return compactObject({
+                id: block.id,
+                type: block.type,
+                title: block.title,
+                items: block.items.map((item) => compactObject({
+                    title: item.title,
+                    url: item.url,
+                    kind: item.kind,
+                    notes: item.notes,
+                })),
+            });
+        case "markdown":
+            return compactObject({
+                id: block.id,
+                type: "markdown",
+                title: block.title,
+                body: block.body,
+            });
+        case "text":
+        default:
+            return compactObject({
+                id: block.id,
+                type: "text",
+                title: block.title,
+                body: block.body,
+            });
+    }
+}
+function serializeCard(card) {
+    return compactObject({
+        id: card.id,
+        type: card.type,
+        status: card.status,
+        prompt: card.prompt,
+        answer: card.answer,
+        tags: card.tags,
+        blockRefs: card.blockRefs,
+        ...(card.type === "coding" && card.exercise
+            ? { exercise: serializeCodingExercise(card.exercise) }
+            : {
+                fsrs: serializeFsrs(card.fsrs),
+                reviews: serializeReviews(card.reviews),
+            }),
+    });
+}
+function serializeCodingExercise(exercise) {
+    return compactObject({
+        id: assertDocsId(exercise.id),
+        difficulty: exercise.difficulty,
+        description: exercise.description,
+        constraints: exercise.constraints,
+        signature: {
+            className: exercise.signature.className,
+            methodName: exercise.signature.methodName,
+            parameters: exercise.signature.parameters.map((parameter) => ({
+                name: parameter.name,
+                type: parameter.type,
+            })),
+            returnType: exercise.signature.returnType,
+        },
+        languages: exercise.languages.map((language) => ({
+            language: language.language,
+            version: language.version,
+            fileName: language.fileName,
+            starterCode: language.starterCode,
+        })),
+        examples: exercise.examples.map((example) => compactObject({
+            id: assertDocsId(example.id),
+            title: example.title,
+            arguments: example.arguments,
+            expected: example.expected,
+            explanation: example.explanation,
+        })),
+        hints: (exercise.hints ?? []).map((hint) => ({
+            id: assertDocsId(hint.id),
+            title: hint.title,
+            body: hint.body,
+        })),
+        solutions: (exercise.solutions ?? []).map((solution) => compactObject({
+            language: solution.language,
+            explanation: solution.explanation,
+            code: solution.code,
+        })),
+    });
+}
+export function docsNoteToFrontmatter(note) {
+    return compactObject({
+        schemaVersion: DOCS_NOTE_SCHEMA_VERSION,
+        id: assertDocsId(note.id),
+        title: note.title,
+        docType: note.docType,
+        summary: note.summary,
+        learningGoal: note.learningGoal,
+        aliases: note.aliases,
+        tags: note.tags,
+        book: serializeBook(note.book),
+        bookId: note.bookId,
+        completedAt: note.completedAt,
+        createdAt: note.createdAt,
+        updatedAt: note.updatedAt,
+        blocks: note.blocks.map(serializeBlock),
+        cards: note.cards.map(serializeCard),
+    });
+}
+export function docsNoteToMarkdown(note) {
+    const frontmatter = docsNoteToFrontmatter(note);
+    const body = note.body.trim();
+    return `---\n${YAML.stringify(frontmatter, { lineWidth: 100 }).trimEnd()}\n---\n${body ? `\n${body}\n` : ""}`;
+}
+function markdownHeading(level, title) {
+    return `${"#".repeat(Math.max(1, Math.min(level, 6)))} ${title}`;
+}
+function compactMarkdown(parts) {
+    return parts
+        .map((part) => part?.trim())
+        .filter((part) => Boolean(part))
+        .join("\n\n");
+}
+function markdownList(items, ordered = false) {
+    return items
+        .map((item, index) => `${ordered ? `${index + 1}.` : "-"} ${item}`)
+        .join("\n");
+}
+function markdownTableCell(value) {
+    return value.replaceAll("|", "\\|").replace(/\s+/g, " ").trim();
+}
+function markdownTable(columns, rows) {
+    if (!columns.length)
+        return "";
+    const header = `| ${columns.map(markdownTableCell).join(" | ")} |`;
+    const separator = `| ${columns.map(() => "---").join(" | ")} |`;
+    const body = rows
+        .map((row) => {
+        const cells = columns.map((_, index) => markdownTableCell(row[index] ?? ""));
+        return `| ${cells.join(" | ")} |`;
+    })
+        .join("\n");
+    return [header, separator, body].filter(Boolean).join("\n");
+}
+function blockTitle(block) {
+    return block.title?.trim() || block.type.replace("-", " ");
+}
+function renderCalloutBody(value) {
+    return value
+        .split(/\r?\n/)
+        .map((line) => `> ${line}`)
+        .join("\n");
+}
+export function renderDocsBlockMarkdown(block, headingLevel = 2) {
+    const title = markdownHeading(headingLevel, blockTitle(block));
+    switch (block.type) {
+        case "concept":
+            return compactMarkdown([
+                title,
+                block.summary,
+                block.keyPoints.length ? markdownList(block.keyPoints) : undefined,
+                block.details,
+            ]);
+        case "procedure":
+            return compactMarkdown([
+                title,
+                block.steps.length ? markdownList(block.steps, true) : undefined,
+                block.notes,
+            ]);
+        case "prompt":
+            return compactMarkdown([
+                title,
+                block.problem,
+                block.requirements.length
+                    ? `${markdownHeading(headingLevel + 1, "Requirements")}\n\n${markdownList(block.requirements)}`
+                    : undefined,
+                block.approach
+                    ? `${markdownHeading(headingLevel + 1, "Approach")}\n\n${block.approach}`
+                    : undefined,
+                block.traps.length
+                    ? `${markdownHeading(headingLevel + 1, "Traps")}\n\n${markdownList(block.traps)}`
+                    : undefined,
+                block.tests.length
+                    ? `${markdownHeading(headingLevel + 1, "Good tests")}\n\n${markdownList(block.tests)}`
+                    : undefined,
+                block.answer
+                    ? `${markdownHeading(headingLevel + 1, "Answer")}\n\n${block.answer}`
+                    : undefined,
+            ]);
+        case "code":
+            return compactMarkdown([
+                title,
+                block.caption,
+                `\`\`\`${block.language}\n${block.code}\n\`\`\``,
+            ]);
+        case "table":
+            return compactMarkdown([title, markdownTable(block.columns, block.rows)]);
+        case "callout":
+            return compactMarkdown([
+                `> [!${block.tone.toUpperCase()}]${block.title ? ` ${block.title}` : ""}`,
+                renderCalloutBody(block.body),
+            ]);
+        case "story":
+            return compactMarkdown([
+                title,
+                block.useFor.length
+                    ? `**Use for:** ${block.useFor.join(", ")}`
+                    : undefined,
+                block.situation ? `**Situation:** ${block.situation}` : undefined,
+                block.task ? `**Task:** ${block.task}` : undefined,
+                block.action ? `**Action:** ${block.action}` : undefined,
+                block.result ? `**Result:** ${block.result}` : undefined,
+                block.metrics.length
+                    ? `${markdownHeading(headingLevel + 1, "Metrics")}\n\n${markdownList(block.metrics)}`
+                    : undefined,
+            ]);
+        case "resources":
+            return compactMarkdown([
+                title,
+                block.items
+                    .map((item) => {
+                    const label = item.url
+                        ? `[${item.title}](${item.url})`
+                        : item.title;
+                    const meta = [item.kind, item.notes].filter(Boolean).join(" - ");
+                    return `- ${label}${meta ? ` - ${meta}` : ""}`;
+                })
+                    .join("\n"),
+            ]);
+        case "markdown":
+            return compactMarkdown([block.title ? title : undefined, block.body]);
+        case "text":
+        default:
+            return compactMarkdown([block.title ? title : undefined, block.body]);
+    }
+}
+export function renderDocsNoteMarkdown(note, options = {}) {
+    const mode = options.mode ?? "document";
+    const intro = compactMarkdown([
+        markdownHeading(1, note.title),
+        note.summary,
+        note.learningGoal ? `**Learning goal:** ${note.learningGoal}` : undefined,
+    ]);
+    const renderedBlocks = note.blocks.map((block) => renderDocsBlockMarkdown(block, mode === "slides" ? 2 : 2));
+    const body = note.body && note.blocks.length
+        ? compactMarkdown([markdownHeading(2, "Additional notes"), note.body])
+        : note.body;
+    if (mode === "slides") {
+        return compactMarkdown([
+            `---\nmarp: true\ntitle: ${JSON.stringify(note.title)}\n---`,
+            [intro, ...renderedBlocks, body]
+                .map((part) => part.trim())
+                .filter(Boolean)
+                .join("\n\n---\n\n"),
+        ]);
+    }
+    return compactMarkdown([intro, ...renderedBlocks, body]);
+}

package/dist/model/sample.d.ts

@@ -0,0 +1,7 @@
+import type { DocsNote } from "./types";
+export declare const SAMPLE_DOCS_BOOK_FOLDER = "sample-docs";
+export declare const SAMPLE_DOCS_BOOK_INDEX_ID = "sample-docs-index";
+export declare const SAMPLE_DOCS_BOOK_TAG = "books/sample-docs";
+export declare const SAMPLE_DOCS_NOTE_IDS: readonly ["sample-docs-schema-harness", "sample-docs-coding-drill", "sample-docs-system-design", "sample-docs-story-bank", "sample-docs-freeform", "sample-docs-index"];
+export declare const SAMPLE_DOCS_CHAPTER_IDS: readonly ["sample-docs-schema-harness", "sample-docs-coding-drill", "sample-docs-system-design", "sample-docs-story-bank", "sample-docs-freeform"];
+export declare function sampleDocsNotes(): DocsNote[];