| name | structural-code-search |
| description | Syntax-aware search with ast-grep and semgrep; ctags for symbol indexes. Use when ripgrep has too many false positives — see search-tool-selection first. |
Structural code search
Tool choice first: search-tool-selection.
Purpose
Match code shapes (AST patterns), run security rule packs, or use symbol indexes.
When to Use
- Refactor targets (function signatures, imports, class shapes)
- Policy/security scans (
semgrep)
- Repeated def/ref jumps (
ctags)
Required Tools
ast-grep (sg), optional semgrep, universal-ctags.
Install
Install blocks are shared — See install-blocks.md.
Windows PowerShell
Use winget blocks from the reference when provisioning a new machine.
WSL2 Ubuntu
Use apt/curl blocks from the reference; symlink fdfind → fd if needed.
macOS
Use Homebrew blocks from the reference.
Common Commands
sg run --pattern 'function $NAME($$$) { $$$ }' --lang javascript src/
semgrep scan --config auto --max-target-bytes 1000000
ctags -R --fields=+n src/
rg "SymbolName" --type-add 'lang:*.xyz' -t lang
Preview ast-grep rewrites with diff before applying (sg run -r).
Agent-Safe Patterns
- Try
rg first for simple literals; escalate here when noisy.
semgrep --dryrun unless user requests fixes.
- See bounded-output-patterns.md.
Commands Requiring Confirmation
Mechanical rewrites and semgrep --fix require user approval. See commands-requiring-confirmation.md.
Troubleshooting
- Language not supported: fall back to
rg with file-type globs.
- semgrep timeout: narrow paths or configs.
Windows Notes
WSL2 Notes
Verification Checklist