ADR-0051: Find in files: a core engine and a bottom results panel

Status: Accepted; scope amended by ADR-0052
Date: 2026-08-19
Deciders: jka
Decision: D51

Context

ADR-0036 anticipated this: with a remote core, only the core can see the project tree, so searching it has to run in the core. The results need a place in the UI.

Decision

Engine: project.search {needle, ?nocase?, ?wholeword?} walks the open project and returns matching lines grouped by file: {count, files, truncated, results: [{path, rel, matches: [{line, col, cols, text}]}]}. It skips .git/, binary files (containing a NUL byte) and oversized files, and caps result rows. count is total occurrences; the list shows one row per matching line. cols lists every occurrence's start column, so the frontend highlights hits without re-matching.
Whole word: a hit counts only when neither neighbour is a letter, digit or underscore (Unicode letters included). The same boundary rule was added to the in-buffer operations, so the find bar and the panel agree.
Results panel: a tool window docked at the bottom, in the manner of Visual Studio's Find Results. It has a query row and a rich list with a header row per file and one row per match; hits are tinted. Ctrl+Shift+F opens it, seeded from the selection; activating a row opens the file at that line. Search runs on Enter, not on each keystroke.

Alternatives considered

The results could have been a tab in the side dock or a separate window. A bottom panel keeps documents in the centre and matches the tool-window model of ADR-0035.

Consequences

This is the first two-level result in the protocol, with an explicit encoder (ADR-0025).
Regular expressions, glob filters and replace across files were deferred and then added in ADR-0052.