5 files changed, 174 insertions, 0 deletions
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index 26cb37c..de19c8f 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -14,6 +14,7 @@ add_library(qtmaildir_lib STATIC
     threadcidmap.cpp
     messageview.cpp
     mainwindow.cpp
+    querycompleter.cpp
 )
 
 target_include_directories(qtmaildir_lib
diff --git a/src/querycompleter.cpp b/src/querycompleter.cpp
new file mode 100644
index 0000000..44ca010
--- /dev/null
+++ b/src/querycompleter.cpp
@@ -0,0 +1,54 @@
+/*
+ * qtmaildir - a Qt6 mail client for notmuch-indexed Maildirs
+ * Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#include "querycompleter.h"
+
+namespace {
+
+/// Start of the token the cursor sits in. The boundary is whitespace or '(',
+/// so "tag:inbox and su" has its last token starting at 14, not at 0.
+int tokenStart(const QString &text, int cursor)
+{
+    int start = cursor;
+    while (start > 0) {
+        const QChar c = text.at(start - 1);
+        if (c.isSpace() || c == QLatin1Char('('))
+            break;
+        --start;
+    }
+    return start;
+}
+
+} // namespace
+
+CompletionContext completionContext(const QString &text, int cursor)
+{
+    CompletionContext ctx;
+
+    if (cursor < 0 || cursor > text.size())
+        return ctx;
+
+    const int start = tokenStart(text, cursor);
+    const QString token = text.mid(start, cursor - start);
+
+    ctx.kind = CompletionContext::Prefix;
+    ctx.stem = token;
+    ctx.replaceFrom = start;
+    ctx.replaceLength = token.size();
+    return ctx;
+}
diff --git a/src/querycompleter.h b/src/querycompleter.h
new file mode 100644
index 0000000..d9635c0
--- /dev/null
+++ b/src/querycompleter.h
@@ -0,0 +1,52 @@
+/*
+ * qtmaildir - a Qt6 mail client for notmuch-indexed Maildirs
+ * Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#pragma once
+
+#include <QString>
+
+/// Where the cursor sits in a query, and therefore what should be offered.
+///
+/// A plain value type produced by a pure function so the parsing rules can be
+/// tested without a widget or a database.
+struct CompletionContext
+{
+    enum Kind {
+        None,    ///< Complete nothing: inside a quoted literal, for instance.
+        Prefix,  ///< Complete a query keyword: tag:, date:, and, or, not.
+        Value,   ///< Complete a value for `prefix`.
+    };
+
+    Kind kind = None;
+
+    /// For Value, the keyword left of ':', lowercased. Empty for Prefix.
+    QString prefix;
+
+    /// The text being matched against the candidates.
+    QString stem;
+
+    /// The exact span an accepted completion overwrites. Covers only the text
+    /// being completed, so accepting never disturbs neighbouring text.
+    int replaceFrom = 0;
+    int replaceLength = 0;
+};
+
+/// Decides what the cursor position implies about completion.
+///
+/// `cursor` is an offset into `text`, as QLineEdit::cursorPosition() returns.
+CompletionContext completionContext(const QString &text, int cursor);
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index e761cb6..c50c5e8 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -19,3 +19,4 @@ add_qtmaildir_test(mailsync)
 add_qtmaildir_test(threadcidmap)
 add_qtmaildir_test(mainwindow)
 add_qtmaildir_test(messageview)
+add_qtmaildir_test(querycompleter)
diff --git a/tests/test_querycompleter.cpp b/tests/test_querycompleter.cpp
new file mode 100644
index 0000000..9278a1e
--- /dev/null
+++ b/tests/test_querycompleter.cpp
@@ -0,0 +1,66 @@
+/*
+ * qtmaildir - a Qt6 mail client for notmuch-indexed Maildirs
+ * Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#include <QtTest>
+
+#include "querycompleter.h"
+
+class TestQueryCompleter : public QObject
+{
+    Q_OBJECT
+
+private slots:
+    void emptyTextCompletesPrefix();
+    void bareWordCompletesPrefix();
+    void wordAfterOperatorCompletesPrefix();
+    void prefixReplaceSpanCoversTheWord();
+};
+
+void TestQueryCompleter::emptyTextCompletesPrefix()
+{
+    const CompletionContext ctx = completionContext(QString(), 0);
+    QCOMPARE(ctx.kind, CompletionContext::Prefix);
+    QCOMPARE(ctx.stem, QString());
+}
+
+void TestQueryCompleter::bareWordCompletesPrefix()
+{
+    const CompletionContext ctx = completionContext(QStringLiteral("su"), 2);
+    QCOMPARE(ctx.kind, CompletionContext::Prefix);
+    QCOMPARE(ctx.stem, QStringLiteral("su"));
+}
+
+void TestQueryCompleter::wordAfterOperatorCompletesPrefix()
+{
+    // The token boundary is whitespace, not the start of the line.
+    const QString text = QStringLiteral("tag:inbox and su");
+    const CompletionContext ctx = completionContext(text, text.size());
+    QCOMPARE(ctx.kind, CompletionContext::Prefix);
+    QCOMPARE(ctx.stem, QStringLiteral("su"));
+}
+
+void TestQueryCompleter::prefixReplaceSpanCoversTheWord()
+{
+    const QString text = QStringLiteral("tag:inbox and su");
+    const CompletionContext ctx = completionContext(text, text.size());
+    QCOMPARE(ctx.replaceFrom, 14);
+    QCOMPARE(ctx.replaceLength, 2);
+}
+
+QTEST_MAIN(TestQueryCompleter)
+#include "test_querycompleter.moc"