textsearch

Documentation

Overview

Package textsearch gives Prism a real full-text search: the literal/substring search an agent would otherwise reach for grep to do. It shells out to the best engine present on the host — ripgrep, then grep — and falls back to a built-in Go scanner so the capability exists on every platform with zero external dependency. The backend choice is Prism's, made once per process; callers (and agents) never pick a binary.

Safety: the pattern is always passed after `-e` and paths after `--`, so a pattern beginning with `-` can never be parsed as an option (same flag-injection posture as verify.go's git guards). Patterns are matched as FIXED STRINGS, case-insensitive — the semantics of an agent's search term, not a regex engine.

Index

• func Backend() string
• type Hit
• type Options
• type Result
  • func Search(ctx context.Context, root, pattern string, opts Options) Result

Functions

func Backend

func Backend() string

Backend reports which engine this process will use: "rg", "grep", or "native". Detected once; the answer never changes within a process.

Types

type Hit

type Hit struct {
	File string `json:"file"`
	Line int    `json:"line"`
	Text string `json:"text"`
}

Hit is one matching line. File is root-relative with forward slashes.

type Options

type Options struct {
	MaxHits    int           // total hits cap (default 100)
	MaxPerFile int           // per-file hits cap (default 20)
	Timeout    time.Duration // default 10s
	// Regex treats pattern as a regular expression instead of a fixed
	// string. A pattern that does not compile falls back to literal — a
	// search that errors is a tool agents route around.
	Regex bool
}

Options bound a search. Zero values get safe defaults.

type Result

type Result struct {
	Hits    []Hit  `json:"hits"`
	Backend string `json:"backend"` // "rg" | "grep" | "native"
	// Truncated: hit caps were reached. TimedOut: the deadline fired before
	// the search finished — the distinction matters because an empty result
	// from a timeout is indistinguishable from "no matches" to a caller, and
	// silently reads as "that string is not in the repo" (measured: a native
	// scan of an unexcluded virtualenv returned nothing for a string in the
	// project's own source).
	Truncated bool `json:"truncated,omitempty"`
	TimedOut  bool `json:"timedOut,omitempty"`
}

Result is the outcome of one search.

func Search

func Search(ctx context.Context, root, pattern string, opts Options) Result

Search finds lines containing pattern (fixed string, case-insensitive) under root. It never returns an error for "no matches" — that is an empty Result. Engine failures fall back to the native scanner rather than erroring: a text search that sometimes fails is a tool agents route around.