Repository Public
1// SP Notes Core2// File: Sources/SPNotesSync/Repositories/SearchRepository.swift3// Description: One search for the apps: the local full-text index (instant, offline) and, when the server can be4// reached, its hybrid / semantic search — merged into one list where every result says where it comes5// from. The local results never wait for the network. See docs/REPOSITORIES.md.6//7// Author: Simon-Pierre Boucher8// Contact: contact@spboucher.ai9import Foundation10import SPNotesAPI11import SPNotesStore1213/// One line of the merged result list.14public struct UnifiedSearchResult: Sendable, Equatable, Identifiable {15 public enum Origin: String, Sendable, Equatable {16 /// Found by the local full-text index only.17 case local18 /// Found by the server only (semantic match, or a page that is not on this device).19 case server20 /// Found by both.21 case both22 }2324 public var pageId: String25 public var title: String26 public var icon: String?27 public var section: String?28 /// Local excerpt with `SPNotesStore.SearchHit.highlightStart / highlightEnd` markers when there is a local29 /// match, else the server excerpt converted to the same markers.30 public var snippet: String31 public var origin: Origin32 /// The passage the server matched: scroll to this block (hybrid mode).33 public var blockId: String?34 public var heading: String?35 /// bm25 of the local index (lower is better); nil without a local match.36 public var localScore: Double?37 /// The server's fused score (higher is better); nil without a server match.38 public var serverScore: Double?39 /// The local page summary, when the page is on this device.40 public var page: PageSummary?4142 public var id: String { pageId + "#" + (blockId ?? "") }43}4445/// The outcome of a search.46public struct SearchOutcome: Sendable, Equatable {47 public var results: [UnifiedSearchResult]48 /// Whether the server took part. False offline, in `.localOnly`, or when it failed (`serverError` says why).49 public var usedServer: Bool50 public var serverError: RepositoryError?51}5253public enum SearchScope: Sendable, Equatable {54 /// The local index only (no request).55 case localOnly56 /// Local index + the server's hybrid search with semantic ranking. **The server embeds the query: one paid57 /// provider call per search** — use it on an explicit "search by meaning" action, not while typing.58 case hybrid59 /// Local index + the server's search without the embedding call (`semantic=0`): free. The default.60 case serverLexical61}6263public struct SearchRepository: Sendable {64 let context: RepositoryContext65 public init(context: RepositoryContext) { self.context = context }6667 /// The local results only: synchronous with the store, for search-as-you-type.68 public func local(_ text: String, filters: SearchFilters = SearchFilters(), limit: Int = 50) async throws -> [UnifiedSearchResult] {69 do {70 return try await context.store.search(query: text, filters: filters, limit: limit).map(Self.result)71 } catch { throw RepositoryError.from(error) }72 }7374 /// Local and server results merged. The server failing (offline, 5xx, no embedding provider) never fails the75 /// search: the local results are returned with `usedServer == false`.76 public func search(_ text: String, scope: SearchScope = .serverLexical, filters: SearchFilters = SearchFilters(), limit: Int = 40) async throws -> SearchOutcome {77 let localHits = try await local(text, filters: filters, limit: limit)78 let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)79 guard scope != .localOnly, !trimmed.isEmpty else { return SearchOutcome(results: localHits, usedServer: false, serverError: nil) }80 var query = SearchQuery(trimmed, mode: .hybrid, limit: min(max(limit, 1), 60), semantic: scope == .serverLexical ? false : nil,81 section: filters.section.flatMap(PageSection.init(rawValue:)), includeArchived: filters.includeArchived)82 query.since = filters.updatedAfter.map { String(APIDate.string(from: $0).prefix(10)) }83 query.until = filters.updatedBefore.map { String(APIDate.string(from: $0).prefix(10)) }84 let remote: [SPNotesAPI.SearchHit]85 do {86 remote = try await context.api.search(query)87 } catch {88 return SearchOutcome(results: localHits, usedServer: false, serverError: RepositoryError.from(error))89 }90 return SearchOutcome(results: await merge(local: localHits, remote: remote, limit: limit), usedServer: true, serverError: nil)91 }9293 /// Merges the two lists: a page found by both is labelled `.both` and keeps the local excerpt with the server's94 /// passage anchor; pages found by both come first (in the server's order), then the rest interleaved by rank95 /// (reciprocal-rank fusion), so that neither source hides the other.96 func merge(local: [UnifiedSearchResult], remote: [SPNotesAPI.SearchHit], limit: Int) async -> [UnifiedSearchResult] {97 var byPage: [String: UnifiedSearchResult] = [:]98 var rank: [String: Double] = [:]99 for (index, hit) in local.enumerated() {100 byPage[hit.pageId] = hit101 rank[hit.pageId, default: 0] += 1.0 / Double(60 + index)102 }103 for (index, hit) in remote.enumerated() {104 guard let pageId = hit.targetPageID else { continue }105 rank[pageId, default: 0] += 1.0 / Double(60 + index)106 if var existing = byPage[pageId] {107 guard existing.origin == .local else { continue } // a second passage of the same page: the first one stands108 existing.origin = .both109 existing.blockId = hit.blockId110 existing.heading = hit.heading111 existing.serverScore = hit.score112 byPage[pageId] = existing113 } else {114 let summary = try? await context.store.summary(id: pageId)115 byPage[pageId] = UnifiedSearchResult(pageId: pageId, title: hit.title ?? summary?.title ?? "", icon: hit.icon ?? summary?.icon, section: hit.section ?? summary?.section,116 snippet: Self.markers(hit.snippet ?? hit.content ?? summary?.preview ?? ""), origin: .server, blockId: hit.blockId,117 heading: hit.heading, localScore: nil, serverScore: hit.score, page: summary)118 }119 }120 let ordered = byPage.values.sorted { a, b in121 let ra = rank[a.pageId] ?? 0, rb = rank[b.pageId] ?? 0122 if ra != rb { return ra > rb }123 return a.pageId < b.pageId124 }125 return Array(ordered.prefix(limit))126 }127128 static func result(_ hit: SPNotesStore.SearchHit) -> UnifiedSearchResult {129 UnifiedSearchResult(pageId: hit.page.id, title: hit.page.title, icon: hit.page.icon, section: hit.page.section, snippet: hit.snippet, origin: .local,130 blockId: nil, heading: nil, localScore: hit.score, serverScore: nil, page: hit.page)131 }132133 /// The server marks matches with U+0001 / U+0002; the apps render one convention, the local one.134 static func markers(_ text: String) -> String {135 String(text.map { $0 == "\u{1}" ? SPNotesStore.SearchHit.highlightStart : ($0 == "\u{2}" ? SPNotesStore.SearchHit.highlightEnd : $0) })136 }137}138