dook: Definition lookup in your code

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

Installation

Install ripgrep, bat, and uv. Then:

uv tool install dook

(It's also on crates.io if you want to build it yourself. Or if you want to be on the cutting edge you can instead cargo install --git https://github.com/pteromys/dook -F stdin,static_python.)

If you want completion assistance in bash or zsh, install either:

• assets/completions/dook.bash as ~/.local/share/bash-completion/completions/dook or
• assets/completions/dook.zsh as a file named _dook somewhere on zsh's fpath.

Example usage

pteromys@delia ~/src/dook $ dook into_iter
───────┬────────────────────────────────────────────────────
       │ File: ./src/range_union.rs
───────┼────────────────────────────────────────────────────
  51   │ impl<'it> IntoIterator for &'it RangeUnion {
 ...   │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ 8< ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
  54   │     fn into_iter(self) -> Self::IntoIter {
  55   │         self.iter()
  56   │     }
───────┴────────────────────────────────────────────────────

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++, GLSL
• Go
• HTML, CSS, Markdown
• JavaScript, TypeScript, TSX
• Lua
• Python, Cython, Jupyter Notebook (as Python fragments in Markdown)
• Rust
• Shell (everything is just assumed to be bash)
• TeX (as LaTeX; requires the tree-sitter CLI)
• YAML

How to add a language

1. Create ~/.config/dook/somelanguage.yml, where somelanguage is one of the keys in src/language_aliases.rs. Crib from any of the files in config/. (python.yml is probably a decent example.)
2. Create a trimmed-down version of the scenario that motivated you to add this language, and put it in test_cases/, named anything you like.
3. Use dook with this language for a week or two. Every time you edit .yml file, consider adding a corresponding example to the file you created in test_cases/.

If you want to roll the dice on submitting a PR (see below), copy your .yml file to config/ and submit a patch adding that and your file from test_cases/. If you're familiar with Rust, add a constant for your language to LanguageName and your list of example search terms to tests/examples.rs. Otherwise I'll add those for you if I ever respond.

Files

Create ~/.config/dook/downloads_policy.txt containing the text yes, ask, or no to control what dook does when it needs to download a language parser from the internet. The default is ask (ask for confirmation every time). If you're paranoid, you might prefer to use ask for a week and then switch to no to get pager integration.

dook creates and uses the following directories for storage:

• ~/.cache/dook/sources for downloaded parsers
• ~/.cache/tree-sitter for compiled parsers, using tree-sitter-loader

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. And if you pipe it to delta you can get syntax highlighting.
• 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

• keep adding more languages
• show all calls to a function instead (git grep -W already gets mostly there so I care less)
• add a recontextualize mode—pipe in ripgrep output to make it look like git grep -W output—which really ought to be an independent utility but would benefit from dook's definitions of what counts as a parent
• make better patterns (particularly for C and C++) now that I'm on tree-sitter 0.23
• descend into external libraries and standard libraries if there's a sane way to look for them

License

MIT

Contributing

Contribute at your own risk! I might ignore your PRs and issues for no good reason, close them without explanation, or rewrite them from scratch and forget to tell you.

By submitting a PR, you agree to license your contributions under the MIT License, credited in the changelog or somewhere reachable from this README.