dook: Definition lookup in your code

Find code definitions using tree-sitter and ripgrep, and pretty-print them using bat.

Installation

Install ripgrep and bat. Build and install with:

cargo install dook

Example usage

pteromys@delia ~/src/dook $ dook write
───────┬────────────────────────────────────────────────────────────────
       │ File: ./src/paging.rs
───────┼────────────────────────────────────────────────────────────────
  61   │ impl std::io::Write for MaybePager {
 ...   │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ 8< ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
  69   │     fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
  70   │         match self.pipe() {
  71   │             Some(pipe) => pipe.write(buf),
  72   │             None => std::io::stdout().write(buf),
  73   │         }
  74   │     }
───────┴────────────────────────────────────────────────────────────────

Also attempts to find assignments, class definitions, etc—because why should you have to figure out the difference before you search? In old javascript codebases there isn't really a difference anyway!

Supported languages

• c
• c++
• go
• javascript
• python
• rust
• typescript
• tsx

Alternatives and prior art

• symbex: find a definition in python, plus some other operating modes; aimed at slicing/splicing code as input/output to an LLM.
• cq: jq-but-for-code, using a more powerful code query syntax, also powered by tree-sitter.
• ast-grep and comby: syntax-aware find-and-replace (so query language supports some form of captures)
• mogglo: lua-scriptable code search and transformation
• git grep -W 'def your_function_name\(' (or a language-specific analogue) is often good enough in a bunch of languages.
• searching directly on GitHub, powered by stack graphs

Goals vs non-goals

• Find definitions.
• Show enough context to answer the usual questions that motivate looking up a definition.
• Minimize user inputs:
  • Amount of thinking the user needs to do before typing the first invocation
  • Amount of output the user needs to read or scroll past to see what they wanted
  • Number of invocations
  • Amount of typing to make each invocation
• Balance responsiveness and thoroughness: explicitly, return results before the user thinks of a follow-up query.
• Sacrifice consistency and machine readability if necessary to improve chances of showing relevant context. (If you want machine-predictable output, use cq instead.)
• Sacrifice disk and RAM footprint for accuracy and my own development time—tree-sitter parsers are maybe 2 megs each on disk, and the codebase you're searching is probably larger. But do try to keep RAM usage an order of magnitude or so smaller than the IDE you're probably procrastinating opening.
• Be open to similar use cases (like find all mutations of a variable or something), but don't let that block getting good at finding definitions.

Possible future work

• more languages (and tests in more languages 😱)
• show all calls to a function instead (git grep -W already gets mostly there so I care less)
• end this project and make it instead a feature of ripgrep (may not be viable because the parsers for all the languages add up to a pretty large binary size; then again maybe rubicon offers some hope)
• make better patterns (particularly for C and C++) now that I'm on tree-sitter 0.23

License

MIT