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()
+    }
+}