---
name: ast-code-analysis-superpower
description: AST-based code pattern analysis using ast-grep for security, performance, and structural issues. Use when (1) reviewing code for security vulnerabilities, (2) analyzing React hook dependencies or performance patterns, (3) detecting structural anti-patterns across large codebases, (4) needing systematic pattern matching beyond manual inspection.
---
# AST-Grep Code Analysis
AST pattern matching identifies code issues through structural recognition rather than line-by-line reading. Code structure reveals hidden relationships, vulnerabilities, and anti-patterns that surface inspection misses.
## Configuration
- **Target Language**:
- **Analysis Focus**:
- **Severity Level**:
- **Framework**:
- **Max Nesting Depth**:
## Prerequisites
```bash
# Install ast-grep (if not available)
npm install -g @ast-grep/cli
# Or: mise install -g ast-grep
```
## Decision Tree: When to Use AST Analysis
```
Code review needed?
|
+-- Simple code (< lines, obvious structure) --> Manual review
|
+-- Complex code (nested, multi-file, abstraction layers)
|
+-- Security review required? --> Use security patterns
+-- Performance analysis? --> Use performance patterns
+-- Structural quality? --> Use structure patterns
+-- Cross-file patterns? --> Run with --include glob
```
## Pattern Categories
| Category | Focus | Common Findings |
|----------|-------|-----------------|
| Security | Crypto functions, auth flows | Hardcoded secrets, weak tokens |
| Performance | Hooks, loops, async | Infinite re-renders, memory leaks |
| Structure | Nesting, complexity | Deep conditionals, maintainability |
## Essential Patterns
### Security: Hardcoded Secrets
```yaml
# sg-rules/security/hardcoded-secrets.yml
id: hardcoded-secrets
language:
rule:
pattern: |
const $VAR = '$LITERAL';
$FUNC($VAR, ...)
meta:
severity:
message: "Potential hardcoded secret detected"
```
### Security: Insecure Token Generation
```yaml
# sg-rules/security/insecure-tokens.yml
id: insecure-token-generation
language:
rule:
pattern: |
btoa(JSON.stringify($OBJ) + '.' + $SECRET)
meta:
severity:
message: "Insecure token generation using base64"
```
### Performance: Hook Dependencies
```yaml
# sg-rules/performance/react-hook-deps.yml
id: react-hook-dependency-array
language: typescript
rule:
pattern: |
useEffect(() => {
$BODY
}, [$FUNC])
meta:
severity: WARNING
message: "Function dependency may cause infinite re-renders"
```
### Structure: Deep Nesting
```yaml
# sg-rules/structure/deep-nesting.yml
id: deep-nesting
language:
rule:
any:
- pattern: |
if ($COND1) {
if ($COND2) {
if ($COND3) {
$BODY
}
}
}
- pattern: |
for ($INIT) {
for ($INIT2) {
for ($INIT3) {
$BODY
}
}
}
meta:
severity: WARNING
message: "Deep nesting (> levels) - consider refactoring"
```
## Running Analysis
```bash
# Security scan
ast-grep run -r sg-rules/security/
# Performance scan on files
ast-grep run -r sg-rules/performance/ --include="*.tsx,*.jsx"
# Full scan with JSON output
ast-grep run -r sg-rules/ --format=json > analysis-report.json
# Interactive mode for investigation
ast-grep run -r sg-rules/ --interactive
```
## Pattern Writing Checklist
- [ ] Pattern matches specific anti-pattern, not general code
- [ ] Uses `inside` or `has` for context constraints
- [ ] Includes `not` constraints to reduce false positives
- [ ] Separate rules per language (JS vs TS)
- [ ] Appropriate severity (/WARNING/INFO)
## Common Mistakes
| Mistake | Symptom | Fix |
|---------|---------|-----|
| Too generic patterns | Many false positives | Add context constraints |
| Missing `inside` | Matches wrong locations | Scope with parent context |
| No `not` clauses | Matches valid patterns | Exclude known-good cases |
| JS patterns on TS | Type annotations break match | Create language-specific rules |
## Verification Steps
1. **Test pattern accuracy**: Run on known-vulnerable code samples
2. **Check false positive rate**: Review first matches manually
3. **Validate severity**: Confirm -level findings are actionable
4. **Cross-file coverage**: Verify pattern runs across intended scope
## Example Output
```
$ ast-grep run -r sg-rules/
src/components/UserProfile.jsx:15: [insecure-tokens] Insecure token generation
src/hooks/useAuth.js:8: [hardcoded-secrets] Potential hardcoded secret
src/components/Dashboard.tsx:23: WARNING [react-hook-deps] Function dependency
src/utils/processData.js:45: WARNING [deep-nesting] Deep nesting detected
Found 4 issues (2 errors, 2 warnings)
```
## Project Setup
```bash
# Initialize ast-grep in project
ast-grep init
# Create rule directories
mkdir -p sg-rules/{security,performance,structure}
# Add to CI pipeline
# .github/workflows/lint.yml
# - run: ast-grep run -r sg-rules/ --format=json
```
## Custom Pattern Templates
### Specific Patterns
```yaml
# Missing key in list rendering
id: missing-list-key
language: typescript
rule:
pattern: |
$ARRAY.map(($ITEM) => <$COMPONENT $$$PROPS />)
constraints:
$PROPS:
not:
has:
pattern: 'key={$_}'
meta:
severity: WARNING
message: "Missing key prop in list rendering"
```
### Async/Await Patterns
```yaml
# Missing error handling in async
id: unhandled-async
language:
rule:
pattern: |
async function $NAME($$$) {
$$$BODY
}
constraints:
$BODY:
not:
has:
pattern: 'try { $$$ } catch'
meta:
severity: WARNING
message: "Async function without try-catch error handling"
```
## Integration with CI/CD
```yaml
# GitHub Actions example
name: AST Analysis
on: [push, pull_request]
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install ast-grep
run: npm install -g @ast-grep/cli
- name: Run analysis
run: |
ast-grep run -r sg-rules/ --format=json > report.json
if grep -q '"severity": ""' report.json; then
echo "Critical issues found!"
exit 1
fi
```
