[dblock]

Closes #11.

Adds fulltext_search_with_highlights so callers receive documents, scores, and complete highlighted field values together:

Artwork.fulltext_search_with_highlights("ghost", fields: [:title]).each do |result|
  result.document          # the original artwork
  result.score             # its search score
  result.highlights[:title] # "A <b>ghost</b> story"
end

Results preserve search ordering, criteria, filters, and max_results. Existing fulltext_search behavior is unchanged. fields selects indexed fields to display; omitted, it includes all fields in the selected index. Unknown fields raise ArgumentError, and index: selects among multiple indexes.

Highlights contain full strings, never snippets. Arrays preserve order and nil elements; nil scalars stay nil. Unmatched text is escaped and retained, including titles when another field matched. Default markup is <b>...</b>; a block can customize it:

Artwork.fulltext_search_with_highlights("ghost", fields: [:title]) do |match|
  "<mark>#{match}</mark>"
end

The block receives an HTML-escaped match after overlapping and adjacent matches are merged. Its returned markup is inserted verbatim and must be trusted; surrounding text is escaped automatically. Output is intended for HTML element content, not attributes, scripts, or URLs.

Also adds document.fulltext_highlights for already-loaded documents and a standalone highlighter without a Mongoid/database dependency. Computed readers, arrays, Unicode normalization, and localized fields are covered. No positional index storage, document mutation, or index rebuild is required.

Matching follows the existing bounded ngrams, not exact substring matching: partial-word highlights and unmarked portions are possible. Stale indexes can return documents without current highlights. Applications must explicitly choose safe fields to display.

Includes regression coverage and README examples. Rebased onto current master.

Prepared by an AI on behalf of @dblock.

[github-actions]

Danger Report

No issues found.

View run