$ show MagicDuck/grug-far.nvim
grug-far.nvim is a Neovim plugin providing an interactive find-and-replace workflow using ripgrep and ast-grep as search backends. It presents a dedicated buffer with editable input fields (search pattern, replacement, files filter, flags, paths) and renders results with highlighting, folding, and line-level diff markers. The plugin supports multiple search engines and replacement interpreters (Lua, Vimscript), history persistence, preview, quickfix integration, and instance-level API for programmatic control. The architecture is modular: an engine abstraction layer, async job processing with libuv, a rendering system using Neovim extmarks, and a task lifecycle manager. It includes a comprehensive screenshot-based test suite and CI workflows. The codebase demonstrates strong software craftsmanship with clean abstractions, reusable patterns, and extensive documentation.
The LLM identified 5 files worth highlighting for reuse:
Provides generic `chain()` and `parallel_process()` functions to compose asynchronous operations using libuv timers and pipes. Can be extracted for any Neovim plugin that needs to sequence or parallelize async tasks with abort support.
A generic sequential processing queue that processes items one at a time with abort support. Designed to handle streaming data (e.g., JSON lines from a subprocess) with error propagation and completion callbacks. Reusable for any pipeline that needs ordered asynchronous processing.
A collection of well-implemented utility functions: `debounce`/`throttle` for rate-limiting, `setTimeout` for delayed execution, `readFileAsync`/`overwriteFileAsync` for non-blocking file I/O, `escape_path_for_cmd` for safe shell escaping, and `str_to_json_list` for parsing JSON arrays. Each function is self-contained and can be extracted for other Lua projects.
Implements a robust options system with deep merging of user-provided options into defaults, plus deprecation warnings for migrated keys. Uses a `with_defaults()` function pattern that can be reused in any plugin requiring layered configuration with backward compatibility.
Spawns an external command and streams its stdout/stderr output line by line, with optional line truncation and abort support. Handles pipe cleanup and error reporting. A generic component for executing external tools asynchronously in Neovim, extractable for any plugin that needs to run shell commands and process output incrementally.