Support Boolean search expressions in match tracing and snippets

Abierto
  • ¿Algo no está bien?
#59 0 comentarios 0 reacciones 1 asignado Ver en GitHub

Los mantenedores suelen responder en 1 día

@kylebernhardy ya está trabajando en esto.

Desde el 3/11/2026.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
node.js, rust
Área
search

Línea de trabajo

Start with the public API in ts/native.ts, the native implementation in src/engine.rs, and the wrapper contract in README.md; inspect how search expressions are represented and how tracing produces spans and snippets. Add tracing support for the same expression tree while preserving the stated bounds and caller-supplied source behavior. Done means the acceptance-criteria cases are tested, including Boolean branches, term modes, and snippet truncation.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

Outcome

Support Boolean search expressions in match tracing and snippets.

Current behavior

Verified by source inspection of the public API and native implementation at the assessed revision; no runtime reproduction was performed. SearchRequest accepts nested Boolean query expressions, while TraceSearchRequest accepts only a simple text clause. Callers cannot pass the full Boolean search expression to highlighting.

Acceptance criteria

  • Accept the same text-expression tree for tracing, with the same validation and term-analysis semantics.
  • Define which positive branches contribute spans and how negated clauses affect eligibility without being highlighted.
  • Retain caller-supplied current source values and UTF-16 half-open offsets; document that tracing does not validate indexed metadata or stale source versions.
  • Test nested AND/OR/NOT, field-restricted clauses, synonyms, phrases, fuzzy/prefix modes, and snippet truncation.
  • Preserve existing trace source/token/span/deadline bounds and complete reporting.

References and scope

Parent: Epic: Extend fulltext search capabilities beyond the initial wrapper API.

Wrapper contract. This is proposed standalone-library capability with no committed release. Application-specific authorization, source projection, and product API integration are outside this issue.

Harper adoption

Adopt Boolean-aware full-text highlights and snippets tracks capability adoption, permission-preserving expression projection, current-source batching and Table/REST qualification. Fulltext owns branch-aware source evidence and spans; Tantivy owns indexed membership/scoring and analysis. Harper must not flatten the expression into independent leaf traces or remove non-highlightable membership fields before evaluating branch truth.

Compatibility release gates

The Node facade deliberately rejects supplied search-only controls on tracing (filter, offset/limit, sorting, aggregations, exact totals and continuations). Older facades tolerated these extra keys; adoption must strip them and document the changed validation. The direct Rust SearchRequest trace carrier retains its existing search-window/collector compatibility; those controls are not executed. This release gate belongs to this feature rather than an unrelated bug issue.

Review-Deferral: 98654a92e7f16d60 severity=minor category=correctness

Before publication reconcile the explanation branch's ABI 15/query API 8 with tracing's ABI 16/query API 9, choose an unused synchronized root/Cargo/platform package version, build matching prebuilds, and verify installed consumer capability negotiation. Current 0.9.0 manifests are development-source versions, not permission to replace published 0.9.0 artifacts.

Review-Deferral: 905a1f6793a5c859 severity=nit category=reliability

Review-Deferral: cbece47d9185266e severity=none category=correctness

Review follow-up

Conservative matching-work charging is intentional and documented: reservation exhaustion can return complete: false even when a more precise accounting scheme could finish. Keep this explicit in completeness guidance; optimize accounting only with measurements and conservative evidence semantics preserved.

Review-Deferral: 86dfd1420e89f1bd severity=minor category=performance

The follow-up implements cross-leaf span deduplication before charging unique capacity, preventing duplicates from hiding a later unique highlight below the cap. It also preserves caller-thrown error provenance when reading request getters. Follow-up commit 684b732 includes near-cap overlap and primitive/object getter regressions, including candidate-ID and time-budget getters. npm run check passes: 199 Rust tests (9 ignored), 606 debug Node tests, 2 packed-consumer tests and 6 production-worker tests. The packed consumer runs the installed Boolean highlighting example. Release compatibility and synchronized artifact gates above remain open.

Nested NOT deliberately suppresses all descendant highlight spans, including double negation. Membership still follows Boolean truth; README and regression tests define this accepted contract.

Review-Deferral: 32c0b12ae9104a58 severity=none category=correctness

Repeated matching leaves deliberately reuse the bounded matcher but can repeat span collection before deduplication. Existing repeated-leaf benchmarks measure this cost; the span candidate buffer remains capped at 1,024. Consider plan-level reuse only with before/after measurements and unchanged branch, work-budget and completeness semantics. The fuzzy-mode name was clarified at final commit 5e51c5c, with 12 targeted Rust and 29 public production tracing tests passing after the rename. Claude, Cursor Composer and Harper-domain review converged at that revision.

Empty candidate sets continue full query preparation so invalid fields and analyzer-dependent options still reject; an early return would change validation semantics.

Review-Deferral: 03cc357f272dd39e severity=none category=performance

Review-Deferral: cf58bfa91afeab91 severity=none category=performance

Comment generated by kAIle (GPT-6)

Lenguaje dominante
Rust
Estrellas
3
Forks
0
Merge medio
15 h 12 min
PR fusionados (30 d)
11

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de HarperFast/fulltext

Todos los issues de HarperFast/fulltext

Issues similares

Más issues de Rust

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.