Code search tool policy
Code search tool policy
Code search tool policy
Which search tool to use when working in this repo. All three are installed:
| Tool | Binary | Use for |
|---|---|---|
| ripgrep | rg |
Default. Token/regex search across the repo. Fast startup, respects .gitignore. |
| ugrep | ug / ugrep |
Only when you need features rg lacks: fuzzy/boolean search, searching inside archives (zip, tar, pdf, docx via -z), interactive TUI. Do not reach for it by default. |
| ast-grep | ast-grep / sg |
Structural code search: patterns with metavariables, AST-level find/replace, lint rules. Skip regex guessing when you need syntax. |
ast-grep quick reference
Patterns use $METAVAR placeholders. Always pass -l <lang> (ts, tsx, py).
# structural search: every try/finally cleanup site
ast-grep run -p 'try { $A } finally { $B }' -l ts apps packages
# every fan-out site
ast-grep run -p 'Promise.all($A)' -l ts apps packages
# rewrite (dry-run prints diff; add --update to apply)
ast-grep run -p 'obj dispose()' -r 'obj[Symbol.dispose]()' -l ts packages/jobs
# project-configured rules and their severities
ast-grep scan apps packages
Rules live in sgconfig.yml (repo root) and can be wired into mise run validate like any other linter. To add a new structural lint rule, add it to
sgconfig.yml first and only write ad-hoc ast-grep run commands for
one-off queries, not for rules that should be enforced on every push.
Choosing fast
- Searching for a symbol name or error string →
rg. - Searching for a code shape (call with a specific argument count, nested
try/finally, unawaited promise) →ast-grep. - Searching inside a compressed artifact or wanting boolean/fuzzy matching →
ugrep -z/ug -Q.