Skip to content

Build your personal knowledge base with Trilium Notes

6.1 KB
Raw Blame
import type { HelpMetaItem } from "@triliumnext/commons";
import becca from "@triliumnext/core/src/becca/becca.js";
import { load } from "@triliumnext/core/src/becca/becca_loader.js";
import blobService from "@triliumnext/core/src/services/blob.js";
import { getContext } from "@triliumnext/core/src/services/context.js";
import { HELP_ASSET_TOKEN, initInAppHelp } from "@triliumnext/core/src/services/in_app_help.js";
import { helpTools } from "@triliumnext/core/src/services/llm/tools/help_tools.js";
import searchService from "@triliumnext/core/src/services/search/services/search.js";
import { getVirtualNoteAssets } from "@triliumnext/core/src/services/virtual_notes.js";
import fs from "fs";
import path from "path";
import { beforeAll, describe, expect, it } from "vitest";

import NodejsInAppHelpProvider from "../src/in_app_help_provider.js";

/**
 * Exercises the in-app help against the artifacts that actually ship — the tree and content
 * `edit-docs` writes into `src/assets/help`. The unit tests around the provider and the injection
 * use stubs; this is the check that the real files still add up to a working help subtree.
 */
describe("in-app help (shipped artifacts)", () => {
    const provider = new NodejsInAppHelpProvider();
    const meta = provider.getHelpHiddenSubtreeData() as HelpMetaItem[];

    beforeAll(() => {
        initInAppHelp(provider);
        getContext().init(() => load());
    });

    it("injects every page of the shipped tree under _help", () => {
        expect(meta.length).toBeGreaterThan(0);

        for (const item of flatten(meta)) {
            const note = becca.getNote(item.id);
            expect(note, `help note ${item.id} ("${item.title}") is missing from becca`).toBeTruthy();
            expect(note?.isVirtual).toBe(true);
            expect(note?.title).toBe(item.title);
        }
    });

    it("serves the content of every page that ships one, through becca and the blob route", () => {
        const pages = contentPages(meta);
        expect(pages.length).toBeGreaterThan(0);

        for (const page of pages) {
            const content = String(becca.getNoteOrThrow(page.id).getContent());
            expect(content, `help page ${page.id} ("${page.title}") has no content`).not.toBe("");

            const pojo = blobService.getBlobPojo("notes", page.id);
            expect(pojo.content).toBe(content);
            expect(pojo.isStubbed).toBe(false);
        }
    });

    it("points every image and attachment at a file the server serves", () => {
        // `getHelpAssetDir` serves these out of the markdown export in a source checkout, and the
        // build copies the same tree into the package.
        const assetRoot = path.resolve(__dirname, "../../../docs/User Guide");
        const missing: string[] = [];
        let assetCount = 0;

        for (const page of contentPages(meta)) {
            const html = String(becca.getNoteOrThrow(page.id).getContent());
            expect(html, `page ${page.id} still carries an unsubstituted asset placeholder`).not.toContain(HELP_ASSET_TOKEN);

            for (const match of html.matchAll(/(?:src|href)="([^"]*\/help\/[^"]*)"/g)) {
                assetCount++;
                const relative = decodeURIComponent(match[1].split("/help/")[1]);
                if (!fs.existsSync(path.join(assetRoot, relative))) {
                    missing.push(`${page.title} -> ${relative}`);
                }
            }
        }

        expect(assetCount).toBeGreaterThan(0);
        expect(missing).toEqual([]);
    });

    it("can read every picture and file an export of the guide carries", async () => {
        const unreadable: string[] = [];
        let assetCount = 0;

        for (const page of contentPages(meta)) {
            for (const asset of getVirtualNoteAssets(page.id)) {
                assetCount++;
                if (await asset.getContent() === null) {
                    unreadable.push(`${page.id} -> ${asset.url}`);
                }
            }
        }

        expect(assetCount).toBeGreaterThan(0);
        expect(unreadable).toEqual([]);
    });

    it("is searchable by its content, but only when the search asks for hidden notes", () => {
        // A phrase from the body of a page, not from any title.
        const query = "docker compose";

        const scoped = searchService.searchNotes(query, { includeHiddenNotes: true });
        expect(scoped.map((note) => note.noteId)).toContain("_help_rWX5eY045zbE");

        // The guide lives under _hidden, so an ordinary search still does not surface it — the
        // virtual pass makes the content matchable, not suddenly present in every result list.
        const ordinary = searchService.searchNotes(query, {});
        expect(ordinary.filter((note) => note.noteId.startsWith("_help"))).toEqual([]);
    });

    it("is searchable by the assistant, by body text and not only by title", () => {
        const searchHelp = Object.fromEntries([ ...helpTools ]).search_help;
        const result = searchHelp.execute({ query: "docker compose" }) as {
            totalResults: number;
            results: { noteId: string; contentPreview: string | null }[];
        };

        // The phrase is in the body of the Docker page and in no title, so a title-only index —
        // which is what an unresolvable content source leaves behind — scores nothing.
        expect(result.totalResults).toBeGreaterThan(0);
        expect(result.results[0].noteId).toBe("_help_rWX5eY045zbE");
        expect(result.results[0].contentPreview).toBeTruthy();
    });

    it("makes every page read-only", () => {
        for (const item of flatten(meta)) {
            expect(becca.getNoteOrThrow(item.id).isContentWritable()).toBe(false);
        }
    });
});

/** Text and code notes carry a page of their own; folders and web views do not. */
function contentPages(items: HelpMetaItem[]) {
    return flatten(items).filter((item) => item.type === "text" || item.type === "code");
}

function flatten(items: HelpMetaItem[], out: HelpMetaItem[] = []): HelpMetaItem[] {
    for (const item of items) {
        out.push(item);
        if (item.children) {
            flatten(item.children, out);
        }
    }
    return out;
}