structural-search_skill

Overview

This skill performs structural code search using ast-grep (sg) so you can find semantic AST patterns instead of brittle text matches. It locates constructs like function calls, imports, class definitions, hooks, and error-handling patterns across languages and supports previewed or applied refactors. Use it to power precise code discovery, large-scale refactors, and security or anti-pattern detection.

How this skill works

You express target patterns using ast-grep's pattern syntax (named identifiers like $NAME, wildcards like $_, and repetition $$$). The sg CLI parses files into ASTs and matches those patterns across a repository, returning contextual results, file lists, counts, or JSON output. It also supports previewed replacements (-r) and applying rewrites (--rewrite), plus language-specific scanning and YAML rule execution.

When to use it

• Find every usage of a function, method, or import across a codebase.
• Locate language-specific constructs (hooks, async/await, try/catch) that regex would miss or mis-match.
• Prepare and preview consistent refactors before applying changes repository-wide.
• Detect anti-patterns, security risks (eval, innerHTML), or language-specific issues.
• Create or validate custom linting and code-quality rules with YAML rule scans.

Best practices

• Start with preview mode (-r without --rewrite) to inspect replacements before applying them.
• Use named captures ($NAME) and $_ to create precise yet flexible patterns.
• Limit scope with --lang or path filters when scanning large repos to reduce noise.
• Combine -A for context or --json for machine-readable results to integrate with scripts.
• Test patterns on representative files before running a wide --rewrite operation.

Example use cases

• Find all console.log calls: sg -p 'console.log($_)' and preview replacing with logger.info($_).
• Locate React hook usage: sg -p 'const [$_, $_] = useState($_)' or sg -p 'useEffect($_, [$$$])'.
• Refactor var to const across JS: sg -p 'var $NAME = $_' -r 'const $NAME = $_' --rewrite.
• Detect insecure patterns: sg -p 'eval($_)' or sg -p '$_.innerHTML = $_' to audit security hotspots.
• Search across languages: sg -p 'def $NAME($$$): $$$' --lang python or sg -p 'pattern' --lang typescript.