aiskillstore/marketplace / skills/0xdarkmatter/structural-search
structural-search
VerifiedSearch code by AST structure using ast-grep. Find semantic patterns like function calls, imports, class definitions instead of text patterns. Triggers on: find all calls to X, search for pattern, refactor usages, find where function is used, structural search, ast-grep, sg.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.1 KB |
| assets/rule-template.yaml | config | 736 B |
| references/advanced-usage.md | markdown | 4.3 KB |
| references/go-rust-patterns.md | markdown | 3.2 KB |
| references/js-ts-patterns.md | markdown | 2.4 KB |
| references/python-patterns.md | markdown | 2.3 KB |
| references/security-patterns.md | markdown | 3.1 KB |
| scripts/.gitkeep | other | 0 B |
| skill-report.json | config | 53.8 KB |
references/advanced-usage.md
View on GitHub# Advanced Usage
Advanced ast-grep features including YAML rules, output formatting, and tool integration.
## Context and Output Options
```bash
# Show surrounding lines (context)
sg -p 'console.log($_)' -A 3 # 3 lines after
sg -p 'console.log($_)' -B 3 # 3 lines before
sg -p 'console.log($_)' -C 3 # 3 lines both
# JSON output (for scripting)
sg -p 'console.log($_)' --json
# File names only
sg -p 'TODO' -l
sg -p 'TODO' --files-with-matches
# Count matches
sg -p 'console.log($_)' --count
# Report format
sg -p 'console.log($_)' --report
```
## Combining with Other Tools
```bash
# Find and process with jq
sg -p 'fetch($_)' --json | jq '.matches[].file'
# Find in specific files
fd -e ts | xargs sg -p 'useState($_)'
# Interactive selection with fzf
sg -p 'console.log($_)' -l | fzf | xargs code
# Parallel search in large codebases
fd -e ts -e tsx | xargs -P 4 sg -p 'useEffect($_)'
# Combine with ripgrep for pre-filtering
rg -l 'useState' | xargs sg -p 'const [$_, $_] = useState($_)'
```
## YAML Rules (Reusable Patterns)
Create `.ast-grep.yml` or `sgconfig.yml` in project root:
```yaml
# Single rule file
id: no-console-log
language: typescript
rule:
pattern: console.log($$$)
message: Remove console.log before committing
severity: warning
```
### Multiple Rules
Create `rules/` directory with individual files:
```yaml
# rules/no-console.yml
id: no-console-log
language: typescript
rule:
pattern: console.log($$$)
message: Remove console.log statements
severity: warning
fix: "// removed: console.log"
---
# rules/prefer-const.yml
id: prefer-const
language: typescript
rule:
pattern: var $NAME = $_
message: Use const instead of var
severity: error
fix: const $NAME = $_
```
### Rule Configuration
```yaml
id: rule-identifier
language: typescript # js, python, go, rust, etc.
rule:
# Match a pattern
pattern: console.log($$$)
# Or use multiple conditions
any:
- pattern: console.log($$$)
- pattern: console.warn($$$)
# Negative patterns
not:
pattern: console.error($$$)
# Inside specific context
inside:
pattern: function $_ { $$$ }
message: "Human-readable warning message"
severity: error | warning | info | hint
note: "Additional context for the developer"
# Optional auto-fix
fix: "replacement code using $METAVARS"
# Optional metadata
metadata:
category: best-practice
references:
- https://example.com/rule-explanation
```
### Running Rules
```bash
# Scan with all rules
sg scan
# Scan specific directory
sg scan src/
# Scan with specific config
sg scan --config sgconfig.yml
# Test rules
sg test
# Auto-fix issues
sg scan --fix
```
## Project Configuration
Create `sgconfig.yml` in project root:
```yaml
# sgconfig.yml
ruleDirs:
- rules/ # Directory containing rule files
- .ast-grep/ # Alternative rules location
testConfigs:
- testDir: rules/tests/
# Ignore patterns
ignores:
- "**/node_modules/**"
- "**/dist/**"
- "**/*.min.js"
# Language-specific settings
languageGlobs:
typescript:
- "**/*.ts"
- "**/*.tsx"
python:
- "**/*.py"
```
## Rule Testing
Create test files for rules:
```yaml
# rules/tests/no-console-test.yml
id: no-console-log
valid:
- const x = 1;
- logger.info("message");
invalid:
- console.log("test");
- console.log(variable);
```
Run tests:
```bash
sg test
```
## Integration Patterns
### Pre-commit Hook
```yaml
# .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: ast-grep
name: ast-grep security
entry: sg scan --fail-on warning
language: system
types: [file]
```
### CI/CD Pipeline
```yaml
# GitHub Actions
- name: AST Security Scan
run: |
sg scan --json > ast-grep-results.json
if [ $(jq '.diagnostics | length' ast-grep-results.json) -gt 0 ]; then
echo "Security issues found"
jq '.diagnostics[]' ast-grep-results.json
exit 1
fi
```
### VS Code Integration
Install `ast-grep.ast-grep-vscode` extension for:
- Real-time pattern matching
- Inline warnings from rules
- Quick fixes
## Performance Tips
```bash
# Limit to specific directories
sg -p 'pattern' src/ lib/
# Use file type filters
sg -p 'pattern' --lang typescript
# Combine with fd for speed
fd -e ts -x sg -p 'pattern' {}
# Parallel processing
find . -name "*.ts" -print0 | xargs -0 -P 4 sg -p 'pattern'
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |