Skip to content

Build your personal knowledge base with Trilium Notes

feat(search): mark the comparisons the search engine will refuse

Elian Dorane816ebe06302
diff --git a/apps/client/src/translations/en/translation.json b/apps/client/src/translations/en/translation.json
index 4ac84063ff..a884af7783 100644
--- a/apps/client/src/translations/en/translation.json
+++ b/apps/client/src/translations/en/translation.json
@@ -4301,6 +4301,13 @@
"pan_fast": "Faster panning"
}
},
+ "search_lint": {
+ "relation_needs_property": "Relations point to a note, so they cannot be checked for equality. Use . instead to access its properties.",
+ "text_needs_contains": "note.text searches the title and content together, so it can only be matched with *=*.",
+ "content_not_ordered": "Note content is text, so it cannot be ordered. Use *=* to match it instead.",
+ "compare_the_title": "Compare the title",
+ "use_operator": "Use {{operator}}"
+ },
"search_completion": {
"note": "Note title, properties and related notes",
"operator_equal": "Equals the whole value",
diff --git a/apps/client/src/widgets/ribbon/SearchStringEditor.tsx b/apps/client/src/widgets/ribbon/SearchStringEditor.tsx
index 749e0141c2..0c043223ff 100644
--- a/apps/client/src/widgets/ribbon/SearchStringEditor.tsx
+++ b/apps/client/src/widgets/ribbon/SearchStringEditor.tsx
@@ -1,9 +1,11 @@
import "./SearchStringEditor.css";
+import type { SearchLintMessages } from "@triliumnext/codemirror/src/extensions/trilium_search_lint";
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 { searchCompletionIcon, searchCompletionSource } from "./search_completions";
interface SearchStringEditorProps {
@@ -41,8 +43,9 @@ export default function SearchStringEditor({ currentValue, noteId, placeholder,
void Promise.all([
import("@triliumnext/codemirror/src/single_line"),
- import("@triliumnext/codemirror/src/extensions/trilium_search_highlighter")
- ]).then(([ { createSingleLineEditor }, { triliumSearchHighlighter } ]) => {
+ import("@triliumnext/codemirror/src/extensions/trilium_search_highlighter"),
+ import("@triliumnext/codemirror/src/extensions/trilium_search_lint")
+ ]).then(([ { createSingleLineEditor }, { triliumSearchHighlighter }, { triliumSearchLinter } ]) => {
if (cancelled || !parentRef.current) {
return;
}
@@ -51,7 +54,7 @@ export default function SearchStringEditor({ currentValue, noteId, placeholder,
parent: parentRef.current,
doc: propsRef.current.currentValue,
placeholder,
- extensions: [ triliumSearchHighlighter ],
+ extensions: [ triliumSearchHighlighter, triliumSearchLinter(searchLintMessages()) ],
completionSource: searchCompletionSource,
completionIcon: searchCompletionIcon,
onChange: (value) => {
@@ -102,3 +105,14 @@ export default function SearchStringEditor({ currentValue, noteId, placeholder,
return <div ref={parentRef} className={clsx("search-string-editor form-control tn-input-field", className)} />;
}
+
+/** Read once the editor is built, so the wording follows a language switched while the app runs. */
+function searchLintMessages(): SearchLintMessages {
+ return {
+ relationNeedsProperty: t("search_lint.relation_needs_property"),
+ textNeedsContains: t("search_lint.text_needs_contains"),
+ contentNotOrdered: t("search_lint.content_not_ordered"),
+ compareTheTitle: t("search_lint.compare_the_title"),
+ useOperator: (operator) => t("search_lint.use_operator", { operator })
+ };
+}
diff --git a/apps/client/src/widgets/ribbon/search_completions.ts b/apps/client/src/widgets/ribbon/search_completions.ts
index 321465e239..b073125a90 100644
--- a/apps/client/src/widgets/ribbon/search_completions.ts
+++ b/apps/client/src/widgets/ribbon/search_completions.ts
@@ -1,5 +1,5 @@
import type { Completion, CompletionContext, CompletionResult } from "@triliumnext/codemirror/src/single_line";
-import { ALLOWED_NOTE_TYPES, MIME_TYPES_DICT, SEARCH_NOTE_PATH, SEARCH_NOTE_PATH_SEGMENTS } from "@triliumnext/commons";
+import { ALLOWED_NOTE_TYPES, allowedSearchOperators, MIME_TYPES_DICT, SEARCH_NOTE_PATH, SEARCH_NOTE_PATH_SEGMENTS } from "@triliumnext/commons";
import { isBuiltinAttribute } from "../../services/attributes";
import { t } from "../../services/i18n";
@@ -482,32 +482,6 @@ function allowedOperators(context: CompletionContext): ReadonlySet<string> | und
return undefined;
}
- const segments = operand.split(".");
- const property = (segments[segments.length - 1] ?? "").toLowerCase();
- const previous = (segments[segments.length - 2] ?? "").toLowerCase();
-
- // The name after `labels.` is the user's own, and says nothing about the comparison.
- if (previous === "labels") {
- return undefined;
- }
-
- // A relation names a note; only a `.`, walking into a property of that note, continues it.
- if (previous === "relations" || (operand.startsWith("~") && segments.length === 1)) {
- return NO_OPERATORS;
- }
-
- if (property === "text") {
- return TEXT_OPERATORS;
- }
-
- if (property === "content" || property === "rawcontent") {
- return CONTENT_OPERATORS;
- }
-
- return undefined;
+ return allowedSearchOperators(operand);
}
-const NO_OPERATORS: ReadonlySet<string> = new Set();
-const TEXT_OPERATORS: ReadonlySet<string> = new Set([ "*=*" ]);
-/** Matches `ALLOWED_OPERATORS` in `note_content_fulltext.ts`: content is matched, never ordered. */
-const CONTENT_OPERATORS: ReadonlySet<string> = new Set([ "=", "!=", "*=*", "*=", "=*", "%=", "~=", "~*" ]);
diff --git a/packages/codemirror/src/extensions/trilium_search_lint.spec.ts b/packages/codemirror/src/extensions/trilium_search_lint.spec.ts
new file mode 100644
index 0000000000..75db4ad952
--- /dev/null
+++ b/packages/codemirror/src/extensions/trilium_search_lint.spec.ts
@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+
+import { diagnoseSearchQuery, type SearchLintMessages } from "./trilium_search_lint.js";
+
+// The wording is the consumer's; the keys identify which rule answered.
+const MESSAGES: SearchLintMessages = {
+ relationNeedsProperty: "relation",
+ textNeedsContains: "text",
+ contentNotOrdered: "content",
+ compareTheTitle: "fix-title",
+ useOperator: (operator) => `fix-${operator}`
+};
+
+describe("diagnoseSearchQuery", () => {
+ it("marks the operator a relation cannot take, and offers the property path in its place", () => {
+ const [ diagnostic, ...rest ] = diagnoseSearchQuery("~author = tolkien", MESSAGES);
+
+ expect(rest).toHaveLength(0);
+ expect(diagnostic.message).toBe("relation");
+ expect(diagnostic.severity).toBe("error");
+ // The operator alone is underlined, not the relation that is spelled correctly.
+ expect([ diagnostic.from, diagnostic.to ]).toEqual([ 8, 9 ]);
+ expect(diagnostic.actions?.[0].name).toBe("fix-title");
+
+ // Reached through a path as well as through the `~` prefix.
+ expect(messagesFor("note.relations.author = x")).toEqual([ "relation" ]);
+ });
+
+ it("repairs a query into one the parser accepts, leaving the property name selected", () => {
+ // Opening the path alone would leave `tolkien` behind it as an unrecognised property, so
+ // the fix names the one the parser's own advice does.
+ expect(applyFirstFix("~author = tolkien")).toEqual({
+ query: "~author.title = tolkien",
+ selected: "title"
+ });
+ expect(applyFirstFix("note.relations.author = x").query).toBe("note.relations.author.title = x");
+
+ expect(applyFirstFix("note.text = hello")).toEqual({ query: "note.text *=* hello", selected: "" });
+ expect(applyFirstFix("note.content >= hello").query).toBe("note.content *=* hello");
+ });
+
+ it("marks an operator the compared property does not accept", () => {
+ expect(messagesFor("note.text = hello")).toEqual([ "text" ]);
+ expect(messagesFor("~author.text > hello")).toEqual([ "text" ]);
+ expect(messagesFor("note.content >= hello")).toEqual([ "content" ]);
+ expect(messagesFor("note.rawContent < hello")).toEqual([ "content" ]);
+
+ const [ diagnostic ] = diagnoseSearchQuery("note.text = hello", MESSAGES);
+ expect(diagnostic.actions?.[0].name).toBe("fix-*=*");
+ });
+
+ it("stays quiet on everything the parser accepts", () => {
+ for (const query of [
+ "~author.title = tolkien",
+ "~author",
+ "#book = 1",
+ "#book",
+ "note.text *=* hello",
+ "note.content *=* hello",
+ "note.content ~= hello",
+ "note.title >= 2019",
+ // A name of the user's own after `labels.` restricts nothing.
+ "note.labels.text = hello",
+ "towers #book or #author",
+ ""
+ ]) {
+ expect(messagesFor(query), query).toEqual([]);
+ }
+ });
+
+ it("leaves an operator alone when a full-text word stands between it and the relation", () => {
+ // `tolkien` is the query's full text, so the operator is not comparing `~author` at all
+ // and the tokenizer does not emit a token for it.
+ expect(messagesFor("~author tolkien = x")).toEqual([]);
+ });
+
+ it("marks each offending comparison in a query that holds several", () => {
+ expect(messagesFor("#book = 1 ~author = x note.text = y")).toEqual([ "relation", "text" ]);
+ });
+});
+
+function messagesFor(query: string) {
+ return diagnoseSearchQuery(query, MESSAGES).map((diagnostic) => diagnostic.message);
+}
+
+/** Applies the first diagnostic's fix against a view that only records what it was handed. */
+function applyFirstFix(query: string) {
+ const [ diagnostic ] = diagnoseSearchQuery(query, MESSAGES);
+ const action = diagnostic?.actions?.[0];
+ if (!action) {
+ throw new Error(`Nothing offered a fix for ${JSON.stringify(query)}.`);
+ }
+
+ let result = { query, selected: "" };
+ const view = {
+ dispatch: ({ changes, selection }: {
+ changes: { from: number, to?: number, insert: string },
+ selection: { anchor: number, head?: number }
+ }) => {
+ const edited = query.slice(0, changes.from) + changes.insert + query.slice(changes.to ?? changes.from);
+ // No `head` is a plain cursor, which selects nothing.
+ result = { query: edited, selected: edited.slice(selection.anchor, selection.head ?? selection.anchor) };
+ }
+ };
+
+ action.apply(view as never, diagnostic.from, diagnostic.to);
+
+ return result;
+}
diff --git a/packages/codemirror/src/extensions/trilium_search_lint.ts b/packages/codemirror/src/extensions/trilium_search_lint.ts
new file mode 100644
index 0000000000..301767da74
--- /dev/null
+++ b/packages/codemirror/src/extensions/trilium_search_lint.ts
@@ -0,0 +1,140 @@
+import { type Diagnostic, linter } from "@codemirror/lint";
+import type { Extension } from "@codemirror/state";
+import { allowedSearchOperators, NO_SEARCH_OPERATORS, TEXT_SEARCH_OPERATORS } from "@triliumnext/commons";
+
+import { type SearchToken, tokenizeSearchQuery } from "./trilium_search_highlighter.js";
+
+/**
+ * The wording a diagnostic is reported with, supplied by the consumer because this package holds no
+ * translation catalogue.
+ */
+export interface SearchLintMessages {
+ /** `~author = hello`, which the parser rejects outright. */
+ relationNeedsProperty: string;
+ /** `note.text = hello`: the virtual property is matched with `*=*` alone. */
+ textNeedsContains: string;
+ /** `note.content > hello`: content is matched rather than ordered. */
+ contentNotOrdered: string;
+ /** Names the fix that compares the related note's title. */
+ compareTheTitle: string;
+ /** Names the fix that writes `operator` in place of the one already there. */
+ useOperator(operator: string): string;
+}
+
+/**
+ * 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.
+ */
+export function triliumSearchLinter(messages: SearchLintMessages): Extension {
+ return linter((view) => diagnoseSearchQuery(view.state.doc.toString(), messages));
+}
+
+/** Runs the rules over `query`, apart from an editor, which is also how the spec drives them. */
+export function diagnoseSearchQuery(query: string, messages: SearchLintMessages): Diagnostic[] {
+ const tokens = tokenizeSearchQuery(query);
+ const diagnostics: Diagnostic[] = [];
+
+ for (const [ index, token ] of tokens.entries()) {
+ if (token.kind !== "operator") {
+ continue;
+ }
+
+ const operand = operandBefore(query, tokens, index);
+ const allowed = operand && allowedSearchOperators(query.slice(operand.from, operand.to));
+ if (!operand || !allowed || allowed.has(query.slice(token.from, token.to))) {
+ continue;
+ }
+
+ diagnostics.push(diagnose(operand, token, allowed, messages));
+ }
+
+ return diagnostics;
+}
+
+/**
+ * The attribute or property path the operator at `operatorIndex` compares, walked back over the
+ * dotted path to whatever opened it. Answers nothing where a word stands between the two: that word
+ * is the query's full text, and the operator compares something else.
+ */
+function operandBefore(query: string, tokens: SearchToken[], operatorIndex: number) {
+ const last = tokens[operatorIndex - 1];
+ if (!last || !OPERAND_KINDS.has(last.kind)) {
+ return null;
+ }
+
+ if (query.slice(last.to, tokens[operatorIndex].from).trim() !== "") {
+ return null;
+ }
+
+ let start = operatorIndex - 1;
+ while (tokens[start].kind === "property") {
+ const before = tokens[start - 1];
+ if (!before || !OPERAND_KINDS.has(before.kind) || before.to !== tokens[start].from) {
+ break;
+ }
+
+ start--;
+ }
+
+ return { from: tokens[start].from, to: last.to };
+}
+
+/** What a path can be walked from, `note` itself being a property token. */
+const OPERAND_KINDS = new Set([ "property", "relation", "label" ]);
+
+function diagnose(
+ operand: { from: number, to: number },
+ operator: SearchToken,
+ allowed: ReadonlySet<string>,
+ messages: SearchLintMessages
+): Diagnostic {
+ const at = { from: operator.from, to: operator.to, severity: "error" } as const;
+
+ // A relation takes no operator at all, so the repair opens a property path in front of the one
+ // written. The name is left selected, so typing over it reaches the rest of the path.
+ if (allowed === NO_SEARCH_OPERATORS) {
+ return {
+ ...at,
+ message: messages.relationNeedsProperty,
+ actions: [ {
+ name: messages.compareTheTitle,
+ apply: (view) => view.dispatch({
+ changes: { from: operand.to, insert: `.${RELATED_NOTE_PROPERTY}` },
+ selection: {
+ anchor: operand.to + 1,
+ head: operand.to + 1 + RELATED_NOTE_PROPERTY.length
+ }
+ })
+ } ]
+ };
+ }
+
+ const isText = allowed === TEXT_SEARCH_OPERATORS;
+
+ return {
+ ...at,
+ message: isText ? messages.textNeedsContains : messages.contentNotOrdered,
+ actions: [ {
+ name: messages.useOperator(CONTAINS),
+ apply: (view) => view.dispatch({
+ changes: { from: operator.from, to: operator.to, insert: CONTAINS },
+ selection: { anchor: operator.from + CONTAINS.length }
+ })
+ } ]
+ };
+}
+
+/** The one operator `note.text` accepts, and the one a rejected content comparison falls back to. */
+const CONTAINS = "*=*";
+
+/**
+ * What a related note is compared by where the query does not say. It is the property the parser's
+ * own error names (`~relation.title=hello`) and the one the user guide leads with, and a repair has
+ * to land on a query that parses: opening the path alone leaves the value behind it unrecognised.
+ */
+const RELATED_NOTE_PROPERTY = "title";
diff --git a/packages/commons/src/lib/search_syntax.ts b/packages/commons/src/lib/search_syntax.ts
index 46f0830e9d..6fe00a0675 100644
--- a/packages/commons/src/lib/search_syntax.ts
+++ b/packages/commons/src/lib/search_syntax.ts
@@ -49,3 +49,48 @@ export const SEARCH_NOTE_PATH_SEGMENTS: readonly string[] = [
...SEARCH_NOTE_PATH.traversals,
...SEARCH_NOTE_PATH.attributeSegments
];
+
+/** Every comparison operator the grammar spells, in the order a reader meets them. */
+export const SEARCH_OPERATORS: readonly string[] = [
+ "=", "!=", "*=*", "=*", "*=", ">", ">=", "<", "<=", "%=", "~=", "~*"
+];
+
+/** A relation names a note; only a `.`, walking into a property of that note, continues it. */
+export const NO_SEARCH_OPERATORS: ReadonlySet<string> = new Set();
+/** `parseNoteProperty()` matches `note.text` and rejects every other operator outright. */
+export const TEXT_SEARCH_OPERATORS: ReadonlySet<string> = new Set([ "*=*" ]);
+/** `ALLOWED_OPERATORS` in `note_content_fulltext.ts`: content is matched, never ordered. */
+export const CONTENT_SEARCH_OPERATORS: ReadonlySet<string> = new Set([
+ "=", "!=", "*=*", "*=", "=*", "%=", "~=", "~*"
+]);
+
+/**
+ * The operators `operand` can be compared with, `undefined` standing for no restriction. Shared by
+ * the completion, which offers only these, and the linter, which marks the ones outside them.
+ *
+ * `operand` is the attribute or property path as it is written: `#book`, `~author`, `note.text`.
+ */
+export function allowedSearchOperators(operand: string): ReadonlySet<string> | undefined {
+ const segments = operand.split(".");
+ const property = (segments[segments.length - 1] ?? "").toLowerCase();
+ const previous = (segments[segments.length - 2] ?? "").toLowerCase();
+
+ // The name after `labels.` is the user's own, and says nothing about the comparison.
+ if (previous === "labels") {
+ return undefined;
+ }
+
+ if (previous === "relations" || (operand.startsWith("~") && segments.length === 1)) {
+ return NO_SEARCH_OPERATORS;
+ }
+
+ if (property === "text") {
+ return TEXT_SEARCH_OPERATORS;
+ }
+
+ if (property === "content" || property === "rawcontent") {
+ return CONTENT_SEARCH_OPERATORS;
+ }
+
+ return undefined;
+}