Супервозможность анализа кода через AST

---
name: ast-code-analysis-superpower
description: Анализ шаблонов кода на основе AST с помощью ast-grep для выявления проблем безопасности, производительности и структуры. Используй при (1) проверке кода на уязвимости, (2) анализе зависимостей хуков React или шаблонов производительности, (3) обнаружении структурных антипаттернов в больших кодовых базах, (4) необходимости систематического сопоставления шаблонов, выходящего за рамки ручной проверки.
---

# Анализ кода с AST-Grep

Сопоставление AST-шаблонов выявляет проблемы кода через распознавание структуры, а не построчное чтение. Структура кода раскрывает скрытые связи, уязвимости и антипаттерны, которые упускает поверхностная проверка.

## Конфигурация

- **Целевой язык**: ${language:javascript}
- **Направление анализа**: ${analysis_focus:security}
- **Уровень серьёзности**: ${severity_level:ERROR}
- **Фреймворк**: ${framework:React}
- **Максимальная глубина вложенности**: ${max_nesting:3}

## Предварительные требования

```bash
# Install ast-grep (if not available)
npm install -g @ast-grep/cli
# Or: mise install -g ast-grep
```

## Дерево решений: когда использовать AST-анализ

```
Нужна проверка кода?
|
+-- Простой код (<${simple_code_lines:50} строк, очевидная структура) --> Ручная проверка
|
+-- Сложный код (вложенность, несколько файлов, слои абстракции)
    |
    +-- Нужна проверка безопасности? --> Используй шаблоны безопасности
    +-- Анализ производительности? --> Используй шаблоны производительности
    +-- Качество структуры? --> Используй структурные шаблоны
    +-- Шаблоны в нескольких файлах? --> Запускай с glob-шаблоном --include
```

## Категории шаблонов

| Категория | Направление | Частые находки |
|----------|-------|-----------------|
| Безопасность | Криптографические функции, процессы аутентификации | Секреты в коде, слабые токены |
| Производительность | Хуки, циклы, асинхронность | Бесконечные повторные рендеры, утечки памяти |
| Структура | Вложенность, сложность | Глубоко вложенные условия, сопровождаемость |

## Основные шаблоны

### Безопасность: секреты, зашитые в код

```yaml
# sg-rules/security/hardcoded-secrets.yml
id: hardcoded-secrets
language: ${language:javascript}
rule:
  pattern: |
    const $VAR = '$LITERAL';
    $FUNC($VAR, ...)
  meta:
    severity: ${severity_level:ERROR}
    message: "Potential hardcoded secret detected"
```

### Безопасность: небезопасная генерация токенов

```yaml
# sg-rules/security/insecure-tokens.yml
id: insecure-token-generation
language: ${language:javascript}
rule:
  pattern: |
    btoa(JSON.stringify($OBJ) + '.' + $SECRET)
  meta:
    severity: ${severity_level:ERROR}
    message: "Insecure token generation using base64"
```

### Производительность: зависимости хуков ${framework:React}

```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"
```

### Структура: глубокая вложенность

```yaml
# sg-rules/structure/deep-nesting.yml
id: deep-nesting
language: ${language:javascript}
rule:
  any:
    - pattern: |
        if ($COND1) {
          if ($COND2) {
            if ($COND3) {
              $BODY
            }
          }
        }
    - pattern: |
        for ($INIT) {
          for ($INIT2) {
            for ($INIT3) {
              $BODY
            }
          }
        }
  meta:
    severity: WARNING
    message: "Deep nesting (>${max_nesting:3} levels) - consider refactoring"
```

## Запуск анализа

```bash
# Security scan
ast-grep run -r sg-rules/security/

# Performance scan on ${framework:React} 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
```

## Проверочный список для написания шаблонов

- [ ] Шаблон соответствует конкретному антипаттерну, а не коду вообще.
- [ ] Использует `inside` или `has` для ограничений контекста.
- [ ] Включает ограничения `not` для уменьшения ложноположительных результатов.
- [ ] Для каждого языка отдельные правила: JS и TS.
- [ ] Соответствующая серьёзность: ${severity_level:ERROR}/WARNING/INFO.

## Частые ошибки

| Ошибка | Симптом | Исправление |
|---------|---------|-----|
| Слишком общие шаблоны | Много ложноположительных результатов | Добавь ограничения контекста |
| Отсутствует `inside` | Совпадения в неподходящих местах | Ограничь область родительским контекстом |
| Нет условий `not` | Совпадения с корректными шаблонами | Исключи заведомо корректные случаи |
| Шаблоны JS применяются к TS | Аннотации типов нарушают сопоставление | Создай правила для конкретного языка |

## Шаги проверки

1. **Проверь точность шаблона**: запусти на образцах кода с известными уязвимостями.
2. **Проверь частоту ложноположительных результатов**: вручную просмотри первые ${sample_size:10} совпадений.
3. **Подтверди серьёзность**: убедись, что находки уровня ${severity_level:ERROR} требуют практических действий.
4. **Охват нескольких файлов**: проверь, что шаблон применяется ко всей намеченной области.

## Пример вывода

```
$ ast-grep run -r sg-rules/
src/components/UserProfile.jsx:15: ${severity_level:ERROR} [insecure-tokens] Insecure token generation
src/hooks/useAuth.js:8: ${severity_level:ERROR} [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)
```

## Настройка проекта

```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
```

## Шаблоны пользовательских правил

### Шаблоны для ${framework:React}

```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

```yaml
# Missing error handling in async
id: unhandled-async
language: ${language:javascript}
rule:
  pattern: |
    async function $NAME($$$) {
      $$$BODY
    }
  constraints:
    $BODY:
      not:
        has:
          pattern: 'try { $$$ } catch'
  meta:
    severity: WARNING
    message: "Async function without try-catch error handling"
```

## Интеграция с 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": "${severity_level:ERROR}"' report.json; then
            echo "Critical issues found!"
            exit 1
          fi
```