Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
feat(search): report what the engine refuses while the query is typed
Elian Doran015284448405
diff --git a/apps/client/src/widgets/ribbon/SearchStringEditor.tsx b/apps/client/src/widgets/ribbon/SearchStringEditor.tsxindex 7813c67e3e..1173c3891d 100644--- a/apps/client/src/widgets/ribbon/SearchStringEditor.tsx+++ b/apps/client/src/widgets/ribbon/SearchStringEditor.tsx@@ -1,11 +1,13 @@import "./SearchStringEditor.css";import type { SearchLintMessages } from "@triliumnext/codemirror/src/extensions/trilium_search_lint";+import type { SearchLintResponse } from "@triliumnext/commons";import type { SingleLineEditor } from "@triliumnext/codemirror/src/single_line";import clsx from "clsx";import { useEffect, useRef } from "preact/hooks";import { t } from "../../services/i18n";+import server from "../../services/server";import { searchCompletionIcon, searchCompletionReactivates, searchCompletionSource } from "./search_completions";interface SearchStringEditorProps {@@ -54,7 +56,7 @@ export default function SearchStringEditor({ currentValue, noteId, placeholder,parent: parentRef.current,doc: propsRef.current.currentValue,placeholder,- extensions: [ triliumSearchHighlighter, triliumSearchLinter(searchLintMessages()) ],+ extensions: [ triliumSearchHighlighter, triliumSearchLinter(searchLintMessages(), validateOnServer) ],completionSource: searchCompletionSource,completionIcon: searchCompletionIcon,activateOnCompletion: searchCompletionReactivates,@@ -107,6 +109,17 @@ export default function SearchStringEditor({ currentValue, noteId, placeholder,return <div ref={parentRef} className={clsx("search-string-editor form-control tn-input-field", className)} />;}+/**+ * Asks the engine to read the query without running it, for the faults the rules in the editor do+ * not cover. Only reached once those rules are satisfied, so a query they already object to costs+ * no request.+ */+async function validateOnServer(searchString: string) {+ const { error } = await server.post<SearchLintResponse>("search/lint", { searchString });++ return error;+}+/** Read once the editor is built, so the wording follows a language switched while the app runs. */function searchLintMessages(): SearchLintMessages {return {diff --git a/packages/codemirror/src/extensions/trilium_search_lint.spec.ts b/packages/codemirror/src/extensions/trilium_search_lint.spec.tsindex 75db4ad952..2dbce440f8 100644--- a/packages/codemirror/src/extensions/trilium_search_lint.spec.ts+++ b/packages/codemirror/src/extensions/trilium_search_lint.spec.ts@@ -1,6 +1,6 @@-import { describe, expect, it } from "vitest";+import { describe, expect, it, vi } from "vitest";-import { diagnoseSearchQuery, type SearchLintMessages } from "./trilium_search_lint.js";+import { diagnoseSearchQuery, type SearchLintMessages, searchDiagnostics, type SearchValidator } from "./trilium_search_lint.js";// The wording is the consumer's; the keys identify which rule answered.const MESSAGES: SearchLintMessages = {@@ -79,6 +79,52 @@ describe("diagnoseSearchQuery", () => {});});+describe("searchDiagnostics", () => {+ it("asks the engine only about a query its own rules accept", async () => {+ const validate = vi.fn(async () => "Mixed usage of AND/OR");++ // A fault of its own is reported without a round trip, since the engine would name the+ // same one less precisely.+ expect(await ranges("~author = tolkien", validate)).toEqual([ { from: 8, to: 9, message: "relation" } ]);+ expect(validate).not.toHaveBeenCalled();++ expect(await ranges("#a and #b or #c", validate)).toEqual([+ { from: 0, to: 15, message: "Mixed usage of AND/OR" }+ ]);+ expect(validate).toHaveBeenCalledWith("#a and #b or #c");++ // Nothing to say about an empty field, and nothing to ask.+ validate.mockClear();+ expect(await ranges(" ", validate)).toEqual([]);+ expect(validate).not.toHaveBeenCalled();+ });++ it("keeps the editor working when the engine cannot be reached", async () => {+ const failing = vi.fn(async () => { throw new Error("offline"); });++ expect(await ranges("#a and #b or #c", failing)).toEqual([]);+ expect(failing).toHaveBeenCalled();+ });++ it("drops an answer that describes a query already typed over", async () => {+ const diagnostics = await searchDiagnostics(+ "#a and #b or #c",+ MESSAGES,+ async () => "Mixed usage of AND/OR",+ () => "#a and #b"+ );++ expect(diagnostics).toEqual([]);+ });+});++/** Drives the real lint source and keeps only what a squiggle is drawn from. */+async function ranges(query: string, validate: SearchValidator) {+ const diagnostics = await searchDiagnostics(query, MESSAGES, validate);++ return diagnostics.map(({ from, to, message }) => ({ from, to, message }));+}+function messagesFor(query: string) {return diagnoseSearchQuery(query, MESSAGES).map((diagnostic) => diagnostic.message);}diff --git a/packages/codemirror/src/extensions/trilium_search_lint.ts b/packages/codemirror/src/extensions/trilium_search_lint.tsindex 301767da74..1d6214b3ba 100644--- a/packages/codemirror/src/extensions/trilium_search_lint.ts+++ b/packages/codemirror/src/extensions/trilium_search_lint.ts@@ -21,17 +21,64 @@ export interface SearchLintMessages {useOperator(operator: string): string;}+/**+ * Reads a query by the engine's own rules, without running it. Answers the first fault, or `null`+ * where the query has none.+ */+export type SearchValidator = (query: string) => Promise<string | null>;+/*** Marks the comparisons `parse.ts` refuses, which a query reaches only by being rewritten: no token* typed after `~author =` makes it valid again, so a completion has nothing to offer there and the* mistake would otherwise surface only once the search is run.*- * It reads the same tokens the highlighter colours and holds to what they decide on their own. The- * parser in `trilium-core` stays the authority on whether a query is valid, and the error it- * reports is still what the ribbon shows.+ * The rules below read the same tokens the highlighter colours and hold to what they decide on+ * their own, which keeps them instant and lets them mark the operator they object to. `validate`+ * covers the rest of what the engine refuses, at the cost of a round trip and of a message it can+ * only attach to the whole query, since `SearchContext` records no offsets.+ */+export function triliumSearchLinter(messages: SearchLintMessages, validate?: SearchValidator): Extension {+ return linter((view) => searchDiagnostics(+ view.state.doc.toString(),+ messages,+ validate,+ () => view.state.doc.toString()+ ));+}++/**+ * The lint source, apart from an editor, which is also how the spec drives it. `currentQuery` is+ * read again once `validate` answers, so a message describing text already typed over is dropped.*/-export function triliumSearchLinter(messages: SearchLintMessages): Extension {- return linter((view) => diagnoseSearchQuery(view.state.doc.toString(), messages));+export async function searchDiagnostics(+ query: string,+ messages: SearchLintMessages,+ validate?: SearchValidator,+ currentQuery: () => string = () => query+): Promise<Diagnostic[]> {+ const local = diagnoseSearchQuery(query, messages);++ // The local rules already name a fault, and the engine would only report the same one again,+ // less precisely. They also answer for an empty query, which has nothing to say.+ if (local.length > 0 || !validate || query.trim() === "") {+ return local;+ }++ let error: string | null;+ try {+ error = await validate(query);+ } catch {+ // The editor keeps working without the engine's opinion.+ return [];+ }++ // Typing during the round trip has already queued another run, whose answer describes what the+ // query says now.+ if (!error || currentQuery() !== query) {+ return [];+ }++ return [ { from: 0, to: query.length, severity: "error", message: error } ];}/** Runs the rules over `query`, apart from an editor, which is also how the spec drives them. */diff --git a/packages/commons/src/lib/server_api.ts b/packages/commons/src/lib/server_api.tsindex 4d39246c34..fb217165bf 100644--- a/packages/commons/src/lib/server_api.ts+++ b/packages/commons/src/lib/server_api.ts@@ -361,6 +361,16 @@ export interface SearchResultDetailsRequest {noteIds: string[];}+/** Request body for `POST /api/search/lint`, which reads a query without running it. */+export interface SearchLintRequest {+ searchString: string;+}++/** Response for `POST /api/search/lint`: the first fault in the query, or `null` where it has none. */+export interface SearchLintResponse {+ error: string | null;+}+/*** Per-note snippet + highlight details for one search result, built lazily for a* page of results. Snippet fields are absent when there is nothing to show (e.g.diff --git a/packages/trilium-core/src/routes/api/search.ts b/packages/trilium-core/src/routes/api/search.tsindex 66270ce7e5..558b6902c6 100644--- a/packages/trilium-core/src/routes/api/search.ts+++ b/packages/trilium-core/src/routes/api/search.ts@@ -1,6 +1,7 @@import {- dayjs, type SearchResultDetails, type SearchResultDetailsRequest,- type SearchResultDetailsResponse, type SearchWithTokensResponse, type TemplatesResponse+ dayjs, type SearchLintRequest, type SearchLintResponse, type SearchResultDetails,+ type SearchResultDetailsRequest, type SearchResultDetailsResponse, type SearchWithTokensResponse,+ type TemplatesResponse} from "@triliumnext/commons";import type { Request } from "../../http_interface";@@ -110,6 +111,21 @@ function getSearchResultDetails(req: Request<{ noteId: string }>): SearchResultD};}+/**+ * Reads a search string without running it, so the editor can report what is wrong with a query+ * while it is being typed rather than once it is run. Carries the message alone: `SearchContext`+ * records no offsets, so the caller cannot mark where the fault is.+ */+function lintSearchString(req: Request): SearchLintResponse {+ const { searchString } = (req.body ?? {}) as Partial<SearchLintRequest>;++ if (typeof searchString !== "string") {+ throw new ValidationError("searchString must be a string.");+ }++ return { error: searchService.validateSearchQuery(searchString) };+}+function quickSearch(req: Request<{ searchString: string }>) {const { searchString } = req.params;@@ -252,6 +268,7 @@ export function isNewTemplate(utcDateCreated: string | null, rootCreationDate: s}export default {+ lintSearchString,searchFromNote,getSearchResultDetails,searchAndExecute,diff --git a/packages/trilium-core/src/routes/api/search_lint.spec.ts b/packages/trilium-core/src/routes/api/search_lint.spec.tsnew file mode 100644index 0000000000..19bbbf98c5--- /dev/null+++ b/packages/trilium-core/src/routes/api/search_lint.spec.ts@@ -0,0 +1,51 @@+import type { SearchLintResponse } from "@triliumnext/commons";+import { beforeAll, describe, expect, it } from "vitest";++import { CoreApiTester } from "../../test/api_tester";++let api: CoreApiTester;++describe("Search lint (core)", () => {+ beforeAll(() => {+ api = CoreApiTester.build();+ });++ it("answers nothing for a query the engine accepts", async () => {+ for (const searchString of [ "", "towers #book", "~author.title = tolkien", "note.text *=* hello" ]) {+ const res = await api.post("/api/search/lint", { body: { searchString } });++ expect(res.status, searchString).toBe(200);+ expect(res.body, searchString).toEqual({ error: null });+ }+ });++ it("reports the fault in a query the engine refuses", async () => {+ const res = await api.post<SearchLintResponse>("/api/search/lint", { body: { searchString: "~author = tolkien" } });++ expect(res.status).toBe(200);+ expect(res.body.error).toContain("Relation can be compared only with property");++ // Faults the client's own rules do not cover, which is the point of asking the engine.+ const mixed = await api.post<SearchLintResponse>("/api/search/lint", { body: { searchString: "#a and #b or #c" } });+ expect(mixed.body.error).toContain("Mixed usage of AND/OR");++ const ordering = await api.post<SearchLintResponse>("/api/search/lint", { body: { searchString: "#book orderBy foo" } });+ expect(ordering.body.error).toContain("must start with 'note'");+ });++ it("describes a query cut short rather than throwing out of the route", async () => {+ // `parseNoteProperty` reads the token past the end of these, so validation has to survive it.+ for (const searchString of [ "note.labels", "note.relations", "note.parents" ]) {+ const res = await api.post<SearchLintResponse>("/api/search/lint", { body: { searchString } });++ expect(res.status, searchString).toBe(200);+ expect(res.body.error, searchString).toBeTruthy();+ }+ });++ it("refuses a body that carries no query", async () => {+ const res = await api.post("/api/search/lint", { body: {} });++ expect(res.status).toBe(400);+ });+});diff --git a/packages/trilium-core/src/routes/index.ts b/packages/trilium-core/src/routes/index.tsindex 11d2d5d87c..545b2ae673 100644--- a/packages/trilium-core/src/routes/index.ts+++ b/packages/trilium-core/src/routes/index.ts@@ -240,6 +240,9 @@ export function buildSharedApiRoutes({ route, asyncRoute, asyncRouteWithoutTransapiRoute(PST, "/api/search-note/:noteId/result-details", searchRoute.getSearchResultDetails);apiRoute(PST, "/api/search-and-execute-note/:noteId", searchRoute.searchAndExecute);apiRoute(PST, "/api/search-related", searchRoute.getRelatedNotes);+ // Ahead of the `:searchString` catch-all below, which would otherwise claim the literal path+ // were it ever given a POST handler too.+ apiRoute(PST, "/api/search/lint", searchRoute.lintSearchString);apiRoute(GET, "/api/search/:searchString", searchRoute.search);apiRoute(GET, "/api/search-templates", searchRoute.searchTemplates);diff --git a/packages/trilium-core/src/services/search/services/search.ts b/packages/trilium-core/src/services/search/services/search.tsindex 240222586b..47d255c837 100644--- a/packages/trilium-core/src/services/search/services/search.ts+++ b/packages/trilium-core/src/services/search/services/search.ts@@ -484,6 +484,30 @@ function parseQueryToExpression(query: string, searchContext: SearchContext) {return expression;}+/**+ * Reads `query` the way a search would, and answers the first thing wrong with it, or `null` where+ * nothing is. Nothing is executed, so this costs a lex and a parse rather than a search.+ *+ * Two things the caller has to live with. `SearchContext` keeps only the first error, so a query+ * holding several faults reports the earliest. And some faults are only found while the search+ * runs — `note.content >= x` parses and is refused by `NoteContentFulltextExp` — so silence here+ * is not a promise that the search will succeed.+ */+function validateSearchQuery(query: string): string | null {+ const searchContext = new SearchContext();+ searchContext.originalQuery = query;++ try {+ parseQueryToExpression(query || "", searchContext);+ } catch (e: unknown) {+ // The parser reads past the end of a query cut short after `note.labels` and the like, so a+ // validator that let the throw out would fail on the very text it exists to describe.+ return e instanceof Error ? e.message : String(e);+ }++ return searchContext.getError();+}+function searchNotes(query: string, params: SearchParams = {}): BNote[] {const searchResults = findResultsWithQuery(query, new SearchContext(params));@@ -897,6 +921,7 @@ export default {findResultsWithQuery,findFirstNoteWithQuery,searchNotes,+ validateSearchQuery,extractContentSnippet,extractAttributeSnippet,highlightSearchResults