feat(search): add query engine — SearchQuery, QueryParser, QuerySerializer, KindRegistry

Phase 1 of advanced search. Recursive descent parser for operators (from:, kind:, since:, until:, lang:, domain:, #tag, -exclude, OR), serializer for bidirectional sync, kind alias registry with pseudo-kind support. 68 unit tests all passing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-10 11:42:13 +02:00
parent 0e124f3017
commit ae76b86ab6
7 changed files with 1150 additions and 0 deletions
@@ -0,0 +1,67 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.commons.search
+
+import com.vitorpamplona.quartz.nip01Core.metadata.MetadataEvent
+import com.vitorpamplona.quartz.nip10Notes.TextNoteEvent
+import com.vitorpamplona.quartz.nip18Reposts.RepostEvent
+import com.vitorpamplona.quartz.nip23LongContent.LongTextNoteEvent
+import com.vitorpamplona.quartz.nip28PublicChat.admin.ChannelCreateEvent
+import com.vitorpamplona.quartz.nip28PublicChat.admin.ChannelMetadataEvent
+import com.vitorpamplona.quartz.nip53LiveActivities.streaming.LiveActivitiesEvent
+import com.vitorpamplona.quartz.nip54Wiki.WikiNoteEvent
+import com.vitorpamplona.quartz.nip72ModCommunities.definition.CommunityDefinitionEvent
+import com.vitorpamplona.quartz.nip84Highlights.HighlightEvent
+import com.vitorpamplona.quartz.nip99Classifieds.ClassifiedsEvent
+
+object KindRegistry {
+    val aliases: Map<String, List<Int>> =
+        mapOf(
+            "note" to listOf(TextNoteEvent.KIND),
+            "article" to listOf(LongTextNoteEvent.KIND),
+            "repost" to listOf(RepostEvent.KIND),
+            "profile" to listOf(MetadataEvent.KIND),
+            "channel" to listOf(ChannelCreateEvent.KIND, ChannelMetadataEvent.KIND),
+            "live" to listOf(LiveActivitiesEvent.KIND),
+            "community" to listOf(CommunityDefinitionEvent.KIND),
+            "wiki" to listOf(WikiNoteEvent.KIND),
+            "classified" to listOf(ClassifiedsEvent.KIND),
+            "highlight" to listOf(HighlightEvent.KIND),
+        )
+
+    val pseudoKinds: Set<String> = setOf("reply", "media")
+
+    val presets: Map<String, List<Int>> =
+        mapOf(
+            "Notes" to listOf(TextNoteEvent.KIND),
+            "Articles" to listOf(LongTextNoteEvent.KIND),
+            "Media" to listOf(TextNoteEvent.KIND),
+            "Channels" to listOf(ChannelCreateEvent.KIND, ChannelMetadataEvent.KIND),
+            "Communities" to listOf(CommunityDefinitionEvent.KIND),
+            "Wiki" to listOf(WikiNoteEvent.KIND),
+        )
+
+    fun resolve(alias: String): List<Int>? = aliases[alias.lowercase()]
+
+    fun isPseudoKind(alias: String): Boolean = alias.lowercase() in pseudoKinds
+
+    fun nameFor(kind: Int): String? = aliases.entries.find { kind in it.value }?.key
+}
@@ -0,0 +1,346 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.commons.search
+
+import com.vitorpamplona.quartz.nip19Bech32.decodePublicKeyAsHexOrNull
+import kotlinx.collections.immutable.toImmutableList
+import kotlinx.collections.immutable.toPersistentList
+
+sealed interface Token {
+    data class Operator(
+        val name: String,
+        val value: String,
+        val raw: String,
+    ) : Token
+
+    data class Text(
+        val value: String,
+    ) : Token
+
+    data object Or : Token
+
+    data class Quoted(
+        val value: String,
+        val raw: String,
+    ) : Token
+
+    data class Negation(
+        val term: String,
+    ) : Token
+
+    data class Hashtag(
+        val tag: String,
+    ) : Token
+}
+
+object QueryParser {
+    private val KNOWN_OPERATORS = setOf("from", "kind", "since", "until", "lang", "domain")
+
+    fun parse(input: String): SearchQuery {
+        if (input.isBlank()) return SearchQuery.EMPTY
+        val tokens = tokenize(input)
+        return buildQuery(tokens)
+    }
+
+    internal fun tokenize(input: String): List<Token> {
+        val tokens = mutableListOf<Token>()
+        var i = 0
+        val len = input.length
+
+        while (i < len) {
+            // Skip whitespace
+            if (input[i].isWhitespace()) {
+                i++
+                continue
+            }
+
+            // Quoted phrase
+            if (input[i] == '"') {
+                val start = i
+                i++ // skip opening quote
+                val sb = StringBuilder()
+                while (i < len && input[i] != '"') {
+                    sb.append(input[i])
+                    i++
+                }
+                if (i < len) i++ // skip closing quote
+                val value = sb.toString()
+                tokens.add(Token.Quoted(value, input.substring(start, i)))
+                continue
+            }
+
+            // Negation
+            if (input[i] == '-' && i + 1 < len && !input[i + 1].isWhitespace()) {
+                i++ // skip -
+                val word = readWord(input, i)
+                i += word.length
+                if (word.isNotEmpty()) {
+                    tokens.add(Token.Negation(word))
+                }
+                continue
+            }
+
+            // Hashtag
+            if (input[i] == '#' && i + 1 < len && !input[i + 1].isWhitespace()) {
+                i++ // skip #
+                val tag = readWord(input, i)
+                i += tag.length
+                if (tag.isNotEmpty()) {
+                    tokens.add(Token.Hashtag(tag))
+                }
+                continue
+            }
+
+            // Read a word (may be operator:value, OR, or plain text)
+            val word = readWord(input, i)
+            i += word.length
+
+            if (word.isEmpty()) {
+                i++
+                continue
+            }
+
+            // Check for OR keyword
+            if (word == "OR") {
+                tokens.add(Token.Or)
+                continue
+            }
+
+            // Check for operator pattern (word:value)
+            val colonIdx = word.indexOf(':')
+            if (colonIdx > 0) {
+                val opName = word.substring(0, colonIdx).lowercase()
+                val opValue = word.substring(colonIdx + 1)
+                if (opName in KNOWN_OPERATORS && opValue.isNotEmpty()) {
+                    tokens.add(Token.Operator(opName, opValue, word))
+                    continue
+                }
+                // Malformed operator (no value or unknown) → treat as text
+            }
+
+            tokens.add(Token.Text(word))
+        }
+
+        return tokens
+    }
+
+    private fun readWord(
+        input: String,
+        start: Int,
+    ): String {
+        var i = start
+        while (i < input.length && !input[i].isWhitespace()) {
+            i++
+        }
+        return input.substring(start, i)
+    }
+
+    private fun buildQuery(tokens: List<Token>): SearchQuery {
+        val authors = mutableListOf<String>()
+        val authorNames = mutableListOf<String>()
+        val kinds = mutableListOf<Int>()
+        val hashtags = mutableListOf<String>()
+        val excludeTerms = mutableListOf<String>()
+        val pseudoKinds = mutableListOf<String>()
+        val textParts = mutableListOf<String>()
+        val orTerms = mutableListOf<String>()
+        var since: Long? = null
+        var until: Long? = null
+        var language: String? = null
+        var domain: String? = null
+
+        // Collect OR groups: text terms separated by OR
+        var i = 0
+        while (i < tokens.size) {
+            when (val token = tokens[i]) {
+                is Token.Operator -> {
+                    when (token.name) {
+                        "from" -> {
+                            val hex = decodePublicKeyAsHexOrNull(token.value)
+                            if (hex != null) {
+                                authors.add(hex)
+                            } else {
+                                authorNames.add(token.value)
+                            }
+                        }
+
+                        "kind" -> {
+                            if (KindRegistry.isPseudoKind(token.value)) {
+                                pseudoKinds.add(token.value.lowercase())
+                            } else {
+                                val resolved = KindRegistry.resolve(token.value)
+                                if (resolved != null) {
+                                    kinds.addAll(resolved)
+                                } else {
+                                    token.value.toIntOrNull()?.let { kinds.add(it) }
+                                        ?: textParts.add(token.raw)
+                                }
+                            }
+                        }
+
+                        "since" -> {
+                            val ts = parseDateToTimestamp(token.value)
+                            if (ts != null) {
+                                since = ts
+                            } else {
+                                textParts.add(token.raw)
+                            }
+                        }
+
+                        "until" -> {
+                            val ts = parseDateToTimestamp(token.value)
+                            if (ts != null) {
+                                until = ts
+                            } else {
+                                textParts.add(token.raw)
+                            }
+                        }
+
+                        "lang" -> {
+                            language = token.value.lowercase()
+                        }
+
+                        "domain" -> {
+                            domain = token.value.lowercase()
+                        }
+                    }
+                }
+
+                is Token.Text -> {
+                    // Check if this is part of an OR chain
+                    if (i + 2 < tokens.size && tokens[i + 1] is Token.Or && tokens[i + 2] is Token.Text) {
+                        // Start of OR chain: collect all terms
+                        orTerms.add(token.value)
+                        i++ // skip to OR
+                        while (i < tokens.size && tokens[i] is Token.Or && i + 1 < tokens.size && tokens[i + 1] is Token.Text) {
+                            i++ // skip OR
+                            orTerms.add((tokens[i] as Token.Text).value)
+                            i++ // skip text
+                        }
+                        continue
+                    } else {
+                        textParts.add(token.value)
+                    }
+                }
+
+                is Token.Quoted -> {
+                    textParts.add(token.raw)
+                }
+
+                is Token.Negation -> {
+                    excludeTerms.add(token.term)
+                }
+
+                is Token.Hashtag -> {
+                    hashtags.add(token.tag)
+                }
+
+                is Token.Or -> {
+                    // Orphaned OR (no adjacent text terms) → treat as text
+                    textParts.add("OR")
+                }
+            }
+            i++
+        }
+
+        // Cap OR terms at 3
+        val cappedOrTerms = orTerms.take(3)
+
+        return SearchQuery(
+            text = textParts.joinToString(" "),
+            authors = authors.distinct().toImmutableList(),
+            authorNames = authorNames.distinct().toImmutableList(),
+            kinds = kinds.distinct().toImmutableList(),
+            since = since,
+            until = until,
+            hashtags = hashtags.distinct().toImmutableList(),
+            excludeTerms = excludeTerms.distinct().toImmutableList(),
+            language = language,
+            domain = domain,
+            orTerms = cappedOrTerms.toPersistentList(),
+            pseudoKinds = pseudoKinds.distinct().toImmutableList(),
+        )
+    }
+
+    internal fun parseDateToTimestamp(dateStr: String): Long? {
+        // ISO 8601 formats: YYYY, YYYY-MM, YYYY-MM-DD
+        return try {
+            val parts = dateStr.split("-")
+            when (parts.size) {
+                1 -> {
+                    val year = parts[0].toIntOrNull() ?: return null
+                    if (year < 1970 || year > 2100) return null
+                    dateToUnix(year, 1, 1)
+                }
+
+                2 -> {
+                    val year = parts[0].toIntOrNull() ?: return null
+                    val month = parts[1].toIntOrNull() ?: return null
+                    if (year < 1970 || year > 2100 || month < 1 || month > 12) return null
+                    dateToUnix(year, month, 1)
+                }
+
+                3 -> {
+                    val year = parts[0].toIntOrNull() ?: return null
+                    val month = parts[1].toIntOrNull() ?: return null
+                    val day = parts[2].toIntOrNull() ?: return null
+                    if (year < 1970 || year > 2100 || month < 1 || month > 12 || day < 1 || day > 31) return null
+                    dateToUnix(year, month, day)
+                }
+
+                else -> {
+                    null
+                }
+            }
+        } catch (_: Exception) {
+            null
+        }
+    }
+
+    private fun dateToUnix(
+        year: Int,
+        month: Int,
+        day: Int,
+    ): Long {
+        // Simple UTC date to unix timestamp calculation
+        // Days from epoch (1970-01-01) to the given date
+        var totalDays = 0L
+
+        // Add days for full years
+        for (y in 1970 until year) {
+            totalDays += if (isLeapYear(y)) 366 else 365
+        }
+
+        // Add days for full months in target year
+        val daysInMonth = intArrayOf(0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31)
+        if (isLeapYear(year)) daysInMonth[2] = 29
+        for (m in 1 until month) {
+            totalDays += daysInMonth[m]
+        }
+
+        // Add remaining days
+        totalDays += (day - 1)
+
+        return totalDays * 86400L
+    }
+
+    private fun isLeapYear(year: Int): Boolean = (year % 4 == 0 && year % 100 != 0) || (year % 400 == 0)
+}
@@ -0,0 +1,113 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.commons.search
+
+import com.vitorpamplona.quartz.nip19Bech32.entities.NPub
+
+object QuerySerializer {
+    fun serialize(query: SearchQuery): String {
+        if (query.isEmpty) return ""
+
+        val parts = mutableListOf<String>()
+
+        // Operators first
+        query.authors.forEach { hex ->
+            val npub =
+                try {
+                    NPub.create(hex)
+                } catch (_: Exception) {
+                    null
+                }
+            parts.add("from:${npub ?: hex}")
+        }
+        query.authorNames.forEach { name ->
+            parts.add("from:$name")
+        }
+        query.kinds.forEach { kind ->
+            val name = KindRegistry.nameFor(kind)
+            parts.add("kind:${name ?: kind}")
+        }
+        query.pseudoKinds.forEach { pseudo ->
+            parts.add("kind:$pseudo")
+        }
+        query.since?.let { ts ->
+            parts.add("since:${timestampToDate(ts)}")
+        }
+        query.until?.let { ts ->
+            parts.add("until:${timestampToDate(ts)}")
+        }
+        query.language?.let { lang ->
+            parts.add("lang:$lang")
+        }
+        query.domain?.let { dom ->
+            parts.add("domain:$dom")
+        }
+
+        // Hashtags
+        query.hashtags.forEach { tag ->
+            parts.add("#$tag")
+        }
+
+        // Free text
+        if (query.text.isNotBlank()) {
+            parts.add(query.text)
+        }
+
+        // OR terms
+        if (query.orTerms.isNotEmpty()) {
+            parts.add(query.orTerms.joinToString(" OR "))
+        }
+
+        // Exclusions last
+        query.excludeTerms.forEach { term ->
+            parts.add("-$term")
+        }
+
+        return parts.joinToString(" ")
+    }
+
+    internal fun timestampToDate(timestamp: Long): String {
+        // Convert unix timestamp to YYYY-MM-DD
+        var remaining = timestamp
+        var year = 1970
+        while (true) {
+            val daysInYear = if (isLeapYear(year)) 366L else 365L
+            val secondsInYear = daysInYear * 86400L
+            if (remaining < secondsInYear) break
+            remaining -= secondsInYear
+            year++
+        }
+
+        val daysInMonth = intArrayOf(0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31)
+        if (isLeapYear(year)) daysInMonth[2] = 29
+
+        var dayOfYear = (remaining / 86400).toInt() + 1
+        var month = 1
+        while (month <= 12 && dayOfYear > daysInMonth[month]) {
+            dayOfYear -= daysInMonth[month]
+            month++
+        }
+
+        return "$year-${month.toString().padStart(2, '0')}-${dayOfYear.toString().padStart(2, '0')}"
+    }
+
+    private fun isLeapYear(year: Int): Boolean = (year % 4 == 0 && year % 100 != 0) || (year % 400 == 0)
+}
@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.commons.search
+
+import androidx.compose.runtime.Immutable
+import kotlinx.collections.immutable.ImmutableList
+import kotlinx.collections.immutable.persistentListOf
+
+@Immutable
+data class SearchQuery(
+    val text: String = "",
+    val authors: ImmutableList<String> = persistentListOf(),
+    val authorNames: ImmutableList<String> = persistentListOf(),
+    val kinds: ImmutableList<Int> = persistentListOf(),
+    val since: Long? = null,
+    val until: Long? = null,
+    val hashtags: ImmutableList<String> = persistentListOf(),
+    val excludeTerms: ImmutableList<String> = persistentListOf(),
+    val language: String? = null,
+    val domain: String? = null,
+    val orTerms: ImmutableList<String> = persistentListOf(),
+    val pseudoKinds: ImmutableList<String> = persistentListOf(),
+) {
+    val isEmpty
+        get() =
+            text.isBlank() &&
+                authors.isEmpty() &&
+                authorNames.isEmpty() &&
+                kinds.isEmpty() &&
+                since == null &&
+                until == null &&
+                hashtags.isEmpty() &&
+                orTerms.isEmpty() &&
+                excludeTerms.isEmpty() &&
+                pseudoKinds.isEmpty() &&
+                language == null &&
+                domain == null
+
+    companion object {
+        val EMPTY = SearchQuery()
+    }
+}
@@ -0,0 +1,103 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.commons.search
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertNull
+import kotlin.test.assertTrue
+
+class KindRegistryTest {
+    @Test
+    fun resolveNote() {
+        assertEquals(listOf(1), KindRegistry.resolve("note"))
+    }
+
+    @Test
+    fun resolveArticle() {
+        assertEquals(listOf(30023), KindRegistry.resolve("article"))
+    }
+
+    @Test
+    fun resolveChannel() {
+        val kinds = KindRegistry.resolve("channel")!!
+        assertTrue(40 in kinds)
+        assertTrue(41 in kinds)
+    }
+
+    @Test
+    fun resolveCaseInsensitive() {
+        assertEquals(KindRegistry.resolve("NOTE"), KindRegistry.resolve("note"))
+    }
+
+    @Test
+    fun resolveUnknown() {
+        assertNull(KindRegistry.resolve("unknown"))
+    }
+
+    @Test
+    fun isPseudoKindReply() {
+        assertTrue(KindRegistry.isPseudoKind("reply"))
+        assertTrue(KindRegistry.isPseudoKind("Reply"))
+    }
+
+    @Test
+    fun isPseudoKindMedia() {
+        assertTrue(KindRegistry.isPseudoKind("media"))
+    }
+
+    @Test
+    fun isNotPseudoKind() {
+        assertFalse(KindRegistry.isPseudoKind("note"))
+        assertFalse(KindRegistry.isPseudoKind("article"))
+    }
+
+    @Test
+    fun nameForKind1() {
+        assertEquals("note", KindRegistry.nameFor(1))
+    }
+
+    @Test
+    fun nameForKind30023() {
+        assertEquals("article", KindRegistry.nameFor(30023))
+    }
+
+    @Test
+    fun nameForUnknownKind() {
+        assertNull(KindRegistry.nameFor(99999))
+    }
+
+    @Test
+    fun allAliasesResolve() {
+        KindRegistry.aliases.forEach { (alias, kinds) ->
+            assertEquals(kinds, KindRegistry.resolve(alias))
+        }
+    }
+
+    @Test
+    fun presetsContainExpectedEntries() {
+        assertTrue(KindRegistry.presets.containsKey("Notes"))
+        assertTrue(KindRegistry.presets.containsKey("Articles"))
+        assertTrue(KindRegistry.presets.containsKey("Media"))
+        assertTrue(KindRegistry.presets.containsKey("Channels"))
+    }
+}
@@ -0,0 +1,284 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.commons.search
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertNull
+import kotlin.test.assertTrue
+
+class QueryParserTest {
+    @Test
+    fun emptyInput() {
+        val q = QueryParser.parse("")
+        assertTrue(q.isEmpty)
+        assertEquals(SearchQuery.EMPTY, q)
+    }
+
+    @Test
+    fun whitespaceOnly() {
+        val q = QueryParser.parse("   ")
+        assertTrue(q.isEmpty)
+    }
+
+    @Test
+    fun plainText() {
+        val q = QueryParser.parse("bitcoin lightning")
+        assertEquals("bitcoin lightning", q.text)
+        assertTrue(q.authors.isEmpty())
+        assertTrue(q.kinds.isEmpty())
+    }
+
+    @Test
+    fun kindOperatorAlias() {
+        val q = QueryParser.parse("kind:note")
+        assertEquals(listOf(1), q.kinds.toList())
+        assertTrue(q.text.isBlank())
+    }
+
+    @Test
+    fun kindOperatorNumeric() {
+        val q = QueryParser.parse("kind:30023")
+        assertEquals(listOf(30023), q.kinds.toList())
+    }
+
+    @Test
+    fun kindOperatorArticle() {
+        val q = QueryParser.parse("kind:article")
+        assertEquals(listOf(30023), q.kinds.toList())
+    }
+
+    @Test
+    fun kindOperatorInvalid() {
+        val q = QueryParser.parse("kind:invalid")
+        // Unresolvable kind → treated as text
+        assertEquals("kind:invalid", q.text)
+        assertTrue(q.kinds.isEmpty())
+    }
+
+    @Test
+    fun pseudoKindReply() {
+        val q = QueryParser.parse("kind:reply")
+        assertTrue(q.kinds.isEmpty())
+        assertEquals(listOf("reply"), q.pseudoKinds.toList())
+    }
+
+    @Test
+    fun pseudoKindMedia() {
+        val q = QueryParser.parse("kind:media")
+        assertTrue(q.kinds.isEmpty())
+        assertEquals(listOf("media"), q.pseudoKinds.toList())
+    }
+
+    @Test
+    fun multipleKinds() {
+        val q = QueryParser.parse("kind:note kind:article")
+        assertEquals(listOf(1, 30023), q.kinds.toList())
+    }
+
+    @Test
+    fun sinceDate() {
+        val q = QueryParser.parse("since:2025-01-01")
+        // 2025-01-01 00:00:00 UTC
+        assertEquals(1735689600L, q.since)
+    }
+
+    @Test
+    fun sinceDateYearOnly() {
+        val q = QueryParser.parse("since:2025")
+        // 2025-01-01 00:00:00 UTC
+        assertEquals(1735689600L, q.since)
+    }
+
+    @Test
+    fun sinceDateYearMonth() {
+        val q = QueryParser.parse("since:2025-06")
+        // 2025-06-01 00:00:00 UTC
+        val q2 = QueryParser.parse("since:2025-06-01")
+        assertEquals(q2.since, q.since)
+    }
+
+    @Test
+    fun sinceInvalidDate() {
+        val q = QueryParser.parse("since:not-a-date")
+        assertNull(q.since)
+        assertEquals("since:not-a-date", q.text)
+    }
+
+    @Test
+    fun untilDate() {
+        val q = QueryParser.parse("until:2025-12-31")
+        assertNull(q.since)
+        assertTrue(q.until != null && q.until!! > 0)
+    }
+
+    @Test
+    fun hashtag() {
+        val q = QueryParser.parse("#bitcoin")
+        assertEquals(listOf("bitcoin"), q.hashtags.toList())
+        assertTrue(q.text.isBlank())
+    }
+
+    @Test
+    fun multipleHashtags() {
+        val q = QueryParser.parse("#bitcoin #nostr")
+        assertEquals(listOf("bitcoin", "nostr"), q.hashtags.toList())
+    }
+
+    @Test
+    fun negationTerm() {
+        val q = QueryParser.parse("-spam")
+        assertEquals(listOf("spam"), q.excludeTerms.toList())
+        assertTrue(q.text.isBlank())
+    }
+
+    @Test
+    fun multipleNegations() {
+        val q = QueryParser.parse("-spam -scam")
+        assertEquals(listOf("spam", "scam"), q.excludeTerms.toList())
+    }
+
+    @Test
+    fun quotedPhrase() {
+        val q = QueryParser.parse("\"exact phrase\"")
+        assertEquals("\"exact phrase\"", q.text)
+    }
+
+    @Test
+    fun orTerms() {
+        val q = QueryParser.parse("bitcoin OR lightning")
+        assertEquals(listOf("bitcoin", "lightning"), q.orTerms.toList())
+        assertTrue(q.text.isBlank())
+    }
+
+    @Test
+    fun orTermsWithOperators() {
+        val q = QueryParser.parse("from:vitor bitcoin OR lightning kind:note")
+        assertEquals(listOf("bitcoin", "lightning"), q.orTerms.toList())
+        assertEquals(listOf(1), q.kinds.toList())
+        // from:vitor → authorNames since it's not a valid npub
+        assertEquals(listOf("vitor"), q.authorNames.toList())
+    }
+
+    @Test
+    fun orTermsCappedAtThree() {
+        val q = QueryParser.parse("a OR b OR c OR d OR e")
+        assertEquals(3, q.orTerms.size)
+        assertEquals(listOf("a", "b", "c"), q.orTerms.toList())
+    }
+
+    @Test
+    fun orphanedOr() {
+        val q = QueryParser.parse("OR")
+        assertEquals("OR", q.text)
+        assertTrue(q.orTerms.isEmpty())
+    }
+
+    @Test
+    fun languageOperator() {
+        val q = QueryParser.parse("lang:en bitcoin")
+        assertEquals("en", q.language)
+        assertEquals("bitcoin", q.text)
+    }
+
+    @Test
+    fun domainOperator() {
+        val q = QueryParser.parse("domain:nostr.com bitcoin")
+        assertEquals("nostr.com", q.domain)
+        assertEquals("bitcoin", q.text)
+    }
+
+    @Test
+    fun combinedQuery() {
+        val q = QueryParser.parse("kind:note since:2025-01-01 #bitcoin -spam lightning")
+        assertEquals(listOf(1), q.kinds.toList())
+        assertEquals(1735689600L, q.since)
+        assertEquals(listOf("bitcoin"), q.hashtags.toList())
+        assertEquals(listOf("spam"), q.excludeTerms.toList())
+        assertEquals("lightning", q.text)
+    }
+
+    @Test
+    fun caseInsensitiveOperators() {
+        val q = QueryParser.parse("FROM:vitor KIND:Note")
+        assertEquals(listOf("vitor"), q.authorNames.toList())
+        assertEquals(listOf(1), q.kinds.toList())
+    }
+
+    @Test
+    fun operatorWithNoValue() {
+        val q = QueryParser.parse("from:")
+        // Malformed → treated as text
+        assertEquals("from:", q.text)
+        assertTrue(q.authors.isEmpty())
+    }
+
+    @Test
+    fun fromWithAuthorName() {
+        val q = QueryParser.parse("from:vitor")
+        assertEquals(listOf("vitor"), q.authorNames.toList())
+        assertTrue(q.authors.isEmpty())
+    }
+
+    @Test
+    fun multipleFromAuthors() {
+        val q = QueryParser.parse("from:alice from:bob")
+        assertEquals(listOf("alice", "bob"), q.authorNames.toList())
+    }
+
+    @Test
+    fun duplicateAuthorsDeduped() {
+        val q = QueryParser.parse("from:vitor from:vitor")
+        assertEquals(1, q.authorNames.size)
+    }
+
+    @Test
+    fun parseDateToTimestamp_validDates() {
+        // 1970-01-01 = 0
+        assertEquals(0L, QueryParser.parseDateToTimestamp("1970-01-01"))
+        // 2000-01-01
+        assertEquals(946684800L, QueryParser.parseDateToTimestamp("2000-01-01"))
+    }
+
+    @Test
+    fun parseDateToTimestamp_invalidDates() {
+        assertNull(QueryParser.parseDateToTimestamp("not-a-date"))
+        assertNull(QueryParser.parseDateToTimestamp("1800-01-01"))
+        assertNull(QueryParser.parseDateToTimestamp("2025-13-01"))
+        assertNull(QueryParser.parseDateToTimestamp("2025-01-32"))
+    }
+
+    @Test
+    fun unicodeInFreeText() {
+        val q = QueryParser.parse("bitcoin 日本語 🚀")
+        assertFalse(q.isEmpty)
+        assertTrue(q.text.contains("日本語"))
+        assertTrue(q.text.contains("🚀"))
+    }
+
+    @Test
+    fun veryLongQuery() {
+        val longText = "word ".repeat(100).trim()
+        val q = QueryParser.parse(longText)
+        assertFalse(q.isEmpty)
+    }
+}
@@ -0,0 +1,177 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.commons.search
+
+import kotlinx.collections.immutable.persistentListOf
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+class QuerySerializerTest {
+    @Test
+    fun emptyQuery() {
+        assertEquals("", QuerySerializer.serialize(SearchQuery.EMPTY))
+    }
+
+    @Test
+    fun textOnly() {
+        val q = SearchQuery(text = "bitcoin")
+        assertEquals("bitcoin", QuerySerializer.serialize(q))
+    }
+
+    @Test
+    fun kindOnly() {
+        val q = SearchQuery(kinds = persistentListOf(1))
+        assertEquals("kind:note", QuerySerializer.serialize(q))
+    }
+
+    @Test
+    fun kindUnknown() {
+        val q = SearchQuery(kinds = persistentListOf(99999))
+        assertEquals("kind:99999", QuerySerializer.serialize(q))
+    }
+
+    @Test
+    fun multipleKinds() {
+        val q = SearchQuery(kinds = persistentListOf(1, 30023))
+        assertEquals("kind:note kind:article", QuerySerializer.serialize(q))
+    }
+
+    @Test
+    fun pseudoKinds() {
+        val q = SearchQuery(pseudoKinds = persistentListOf("reply", "media"))
+        assertEquals("kind:reply kind:media", QuerySerializer.serialize(q))
+    }
+
+    @Test
+    fun sinceDate() {
+        val q = SearchQuery(since = 1735689600L) // 2025-01-01
+        assertEquals("since:2025-01-01", QuerySerializer.serialize(q))
+    }
+
+    @Test
+    fun untilDate() {
+        val q = SearchQuery(until = 1735689600L)
+        assertEquals("until:2025-01-01", QuerySerializer.serialize(q))
+    }
+
+    @Test
+    fun hashtags() {
+        val q = SearchQuery(hashtags = persistentListOf("bitcoin", "nostr"))
+        assertEquals("#bitcoin #nostr", QuerySerializer.serialize(q))
+    }
+
+    @Test
+    fun excludeTerms() {
+        val q = SearchQuery(excludeTerms = persistentListOf("spam", "scam"))
+        assertEquals("-spam -scam", QuerySerializer.serialize(q))
+    }
+
+    @Test
+    fun orTerms() {
+        val q = SearchQuery(orTerms = persistentListOf("bitcoin", "lightning"))
+        assertEquals("bitcoin OR lightning", QuerySerializer.serialize(q))
+    }
+
+    @Test
+    fun language() {
+        val q = SearchQuery(language = "en", text = "bitcoin")
+        assertEquals("lang:en bitcoin", QuerySerializer.serialize(q))
+    }
+
+    @Test
+    fun domain() {
+        val q = SearchQuery(domain = "nostr.com", text = "hello")
+        assertEquals("domain:nostr.com hello", QuerySerializer.serialize(q))
+    }
+
+    @Test
+    fun authorNames() {
+        val q = SearchQuery(authorNames = persistentListOf("vitor"))
+        assertEquals("from:vitor", QuerySerializer.serialize(q))
+    }
+
+    @Test
+    fun combinedQuery() {
+        val q =
+            SearchQuery(
+                authorNames = persistentListOf("vitor"),
+                kinds = persistentListOf(1),
+                since = 1735689600L,
+                hashtags = persistentListOf("bitcoin"),
+                text = "lightning",
+                excludeTerms = persistentListOf("spam"),
+            )
+        val result = QuerySerializer.serialize(q)
+        assertTrue(result.contains("from:vitor"))
+        assertTrue(result.contains("kind:note"))
+        assertTrue(result.contains("since:2025-01-01"))
+        assertTrue(result.contains("#bitcoin"))
+        assertTrue(result.contains("lightning"))
+        assertTrue(result.contains("-spam"))
+    }
+
+    @Test
+    fun orderingOperatorsFirst() {
+        val q =
+            SearchQuery(
+                authorNames = persistentListOf("alice"),
+                kinds = persistentListOf(1),
+                hashtags = persistentListOf("nostr"),
+                text = "hello",
+                excludeTerms = persistentListOf("bad"),
+            )
+        val result = QuerySerializer.serialize(q)
+        val fromIdx = result.indexOf("from:")
+        val kindIdx = result.indexOf("kind:")
+        val hashIdx = result.indexOf("#nostr")
+        val textIdx = result.indexOf("hello")
+        val excludeIdx = result.indexOf("-bad")
+        assertTrue(fromIdx < kindIdx)
+        assertTrue(kindIdx < hashIdx)
+        assertTrue(hashIdx < textIdx)
+        assertTrue(textIdx < excludeIdx)
+    }
+
+    @Test
+    fun timestampToDateEpoch() {
+        assertEquals("1970-01-01", QuerySerializer.timestampToDate(0L))
+    }
+
+    @Test
+    fun timestampToDate2025() {
+        assertEquals("2025-01-01", QuerySerializer.timestampToDate(1735689600L))
+    }
+
+    @Test
+    fun roundtrip() {
+        // Parse a complex query, serialize, parse again — should produce equivalent SearchQuery
+        val input = "kind:note since:2025-01-01 #bitcoin lightning -spam"
+        val q1 = QueryParser.parse(input)
+        val serialized = QuerySerializer.serialize(q1)
+        val q2 = QueryParser.parse(serialized)
+        assertEquals(q1.kinds, q2.kinds)
+        assertEquals(q1.since, q2.since)
+        assertEquals(q1.hashtags, q2.hashtags)
+        assertEquals(q1.excludeTerms, q2.excludeTerms)
+        assertEquals(q1.text, q2.text)
+    }
+}