Сценарий 19: Проверка стандартов на основе справочных документов¶

Инженер по качеству или технический лидер, обеспечивающий соблюдение стандартов кодирования с помощью анализа на основе документов.

Содержание¶

Быстрый старт
Обзор
Документы стандартов
Анализ кода
Композитный режим (Оркестратор)
Команды CLI
Команды TUI
Примеры вопросов
Связанные сценарии

Быстрый старт¶

/select 19

Обзор¶

Сценарий 19 предоставляет анализ кода на основе стандартов с использованием конфигурационных файлов YAML. В отличие от обычного линтинга, он позволяет командам определять собственные стандарты кодирования со ссылками на официальные руководства, документы лучших практик или внутренние политики.

Документ стандартов (YAML) → Извлечение правил → Анализ кода → Отчёт о нарушениях
                                    ↓
                          ┌─────────┴─────────┐
                          ↓                   ↓
                    База правил        Ссылки на документы

Документы стандартов¶

Спецификация формата YAML¶

Документы стандартов определяют правила с категориями, серьёзностью и ссылками:

# company_standards.yaml
name: "Корпоративные стандарты кодирования v2.0"
version: "2.0.0"
last_updated: "2024-12-09"
author: "Инженерная команда"

categories:
  - naming
  - security
  - style
  - documentation
  - error_handling

rules:
  - id: "SEC-001"
    title: "Использовать параметризованные запросы для операций с БД"
    category: security
    severity: error
    description: |
      Все запросы к базе данных должны использовать параметризованные
      запросы или подготовленные выражения для предотвращения SQL-инъекций.
    pattern: "execute\\s*\\(.*%s.*\\)|execute\\s*\\(.*.format\\("
    reference:
      url: "https://owasp.org/Top10/A03_2021-Injection/"
      document: "OWASP Top 10 2021"
      section: "A03:2021 – Injection"
    suggestion: "Использовать cursor.execute(query, params) с плейсхолдерами"
    examples:
      bad: 'cursor.execute("SELECT * FROM users WHERE id = %s" % user_id)'
      good: 'cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))'

  - id: "NAME-001"
    title: "Имена функций должны использовать snake_case"
    category: naming
    severity: warning
    description: "Имена функций должны следовать конвенции snake_case."
    pattern: "def\\s+[a-z]+[A-Z]"
    reference:
      url: "https://peps.python.org/pep-0008/#function-and-variable-names"
      document: "PEP 8"
      section: "Function and Variable Names"
    suggestion: "Переименовать функцию в snake_case"

  - id: "DOC-001"
    title: "Публичные функции должны иметь docstrings"
    category: documentation
    severity: info
    description: "Все публичные функции должны иметь документацию."
    pattern: "^def\\s+[^_].*:\\s*$\\n\\s*[^\\\"']"
    reference:
      document: "Внутренние руководства"
      section: "Стандарты документации"

Импорт и валидация документов¶

> Импортировать документ стандартов company_standards.yaml

╭─────────────── Импорт стандартов ────────────────────────╮
│                                                            │
│  Документ: Корпоративные стандарты кодирования v2.0        │
│  Версия: 2.0.0                                             │
│  Импортировано правил: 15                                  │
│                                                            │
│  Категории:                                                │
│    - naming: 4 правила                                     │
│    - security: 5 правил                                    │
│    - style: 3 правила                                      │
│    - documentation: 2 правила                              │
│    - error_handling: 1 правило                             │
│                                                            │
│  Статус: УСПЕШНО                                           │
│                                                            │
╰────────────────────────────────────────────────────────────╯

Категории правил¶

Категория	Описание	Примеры правил
`naming`	Соглашения об именовании	snake_case, CONSTANT_CASE
`security`	Практики безопасности	Валидация ввода, SQL-инъекции
`style`	Стиль кода	Длина строки, отступы
`documentation`	Документация	Docstrings, комментарии
`error_handling`	Обработка ошибок	Обработка исключений, логирование

Уровни серьёзности¶

Серьёзность	Описание	Действие
`error`	Необходимо исправить перед слиянием	Блокирует CI/CD
`warning`	Следует исправить	Пометка при ревью
`info`	Рассмотреть исправление	Информационное

Анализ кода¶

Проверка по правилам¶

> Проверить src/api/ на соответствие стандартам

╭─────────────── Результаты проверки стандартов ───────────╮
│                                                            │
│  Итого:                                                    │
│  - Всего нарушений: 23                                     │
│  - Ошибок: 5                                               │
│  - Предупреждений: 12                                      │
│  - Информация: 6                                           │
│                                                            │
│  Нарушения:                                                │
│                                                            │
│  - **SEC-001**: Риск SQL-инъекции                          │
│    `src/api/user_handler.py:67`                            │
│    *Рекомендация: Использовать cursor.execute(query, params)*│
│                                                            │
│  - **SEC-001**: Риск SQL-инъекции                          │
│    `src/api/data_handler.py:34`                            │
│    *Рекомендация: Использовать cursor.execute(query, params)*│
│                                                            │
│  - **NAME-001**: Функция использует camelCase              │
│    `src/api/helpers.py:23`                                 │
│    *Рекомендация: Переименовать функцию в snake_case*      │
│                                                            │
│  - **DOC-001**: Отсутствует docstring                      │
│    `src/api/utils.py:45`                                   │
│    *Рекомендация: Добавить документацию функции*           │
│                                                            │
│  ... и ещё 19 нарушений                                    │
│                                                            │
╰────────────────────────────────────────────────────────────╯

Отчёт о нарушении со ссылками¶

> Показать детали нарушения SEC-001 в user_handler.py:67

╭─────────────── Детали нарушения ─────────────────────────╮
│                                                            │
│  Правило: SEC-001                                          │
│  Название: Использовать параметризованные запросы          │
│  Серьёзность: ОШИБКА                                       │
│  Категория: security                                       │
│                                                            │
│  Расположение: src/api/user_handler.py:67                  │
│                                                            │
│  Нарушение:                                                │
│  ```python                                                 │
│  cursor.execute("SELECT * FROM users WHERE id = %s" % id)  │
│  ```                                                       │
│                                                            │
│  Рекомендация:                                             │
│  Использовать cursor.execute(query, params) с плейсхолдерами│
│                                                            │
│  Ссылка:                                                   │
│  OWASP Top 10 2021 - A03:2021 – Injection                  │
│  https://owasp.org/Top10/A03_2021-Injection/               │
│                                                            │
╰────────────────────────────────────────────────────────────╯

Фильтрация по категории или серьёзности¶

> Проверить src/ только на ошибки безопасности

╭─────────────── Ошибки безопасности ──────────────────────╮
│                                                            │
│  Фильтр: category=security, severity=error                 │
│  Всего нарушений: 5                                        │
│                                                            │
│  - **SEC-001**: SQL-инъекция в user_handler.py:67          │
│  - **SEC-001**: SQL-инъекция в data_handler.py:34          │
│  - **SEC-002**: Отсутствует валидация ввода в api.py:89    │
│  - **SEC-003**: Жёстко заданные учётные данные в config.py:12│
│  - **SEC-004**: Небезопасная десериализация в parser.py:56 │
│                                                            │
╰────────────────────────────────────────────────────────────╯

Композитный режим (Оркестратор)¶

Сценарий 19 может работать как композитный оркестратор, объединяя проверку соответствия с редактированием файлов:

┌─────────────────────────────────────────────────────────────┐
│              КОМПОЗИТНЫЙ ОРКЕСТРАТОР S19                    │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │              ДОКУМЕНТ СТАНДАРТОВ                        │ │
│  │                 (правила YAML)                          │ │
│  └────────────────────────────────────────────────────────┘ │
│                         ↓                                   │
│  ┌────────────────────────────────────────────────────────┐ │
│  │             ВЫЗОВ СЦЕНАРИЕВ                             │ │
│  │       ┌─────────┐           ┌─────────┐                │ │
│  │       │   S08   │           │   S17   │                │ │
│  │       │Соответ. │           │  Правка │                │ │
│  │       └────┬────┘           └────┬────┘                │ │
│  └────────────┼─────────────────────┼─────────────────────┘ │
│               │                     │                       │
│               ↓                     ↓                       │
│  ┌────────────────────────────────────────────────────────┐ │
│  │               ОБОГАЩЕНИЕ ДОКУМЕНТАМИ                    │ │
│  │   (Нарушения связаны с официальными ссылками)           │ │
│  └────────────────────────────────────────────────────────┘ │
│                         ↓                                   │
│                  ДЕЙСТВЕННЫЙ ОТЧЁТ                          │
└─────────────────────────────────────────────────────────────┘

Подсценарии¶

Сценарий	Вклад
S08 (Соответствие)	Правила соответствия стандартам
S17 (Редактирование файлов)	Применение исправлений

Запуск композитного режима¶

# CLI
codegraph composition run "Проверить по company_standards.yaml" -o s19

# API
POST /api/v1/composition/query
{
  "query": "Проверить по company_standards.yaml",
  "orchestrator": "scenario_19",
  "context": {
    "document_path": "company_standards.yaml",
    "file_paths": ["src/"]
  }
}

Команды CLI¶

# Импортировать документ стандартов
codegraph standards import company_standards.yaml

# Валидировать синтаксис документа
codegraph standards validate company_standards.yaml

# Список импортированных правил
codegraph standards list

# Список правил по категории
codegraph standards list --category security

# Проверить код на соответствие стандартам
codegraph standards check src/

# Проверить с фильтрами
codegraph standards check src/ --severity error
codegraph standards check src/ --category security

# Экспортировать отчёт о нарушениях
codegraph standards report src/ --output violations.json

# Очистить импортированные правила
codegraph standards clear

Команды TUI¶

Команда	Описание
`/standards import <файл>`	Импортировать документ стандартов
`/standards list`	Список доступных правил
`/standards check <путь>`	Проверить код на соответствие правилам
`/standards report`	Сгенерировать отчёт о нарушениях
`/standards clear`	Очистить импортированные правила

Примеры вопросов¶

“Импортировать стандарты из company_standards.yaml”
“Проверить src/ на соответствие импортированным стандартам”
“Показать все правила категории security”
“Показать только нарушения серьёзности error”
“Какие правила относятся к категории naming?”
“Сгенерировать отчёт о соответствии для src/api/”

Создание собственных стандартов¶

Минимальный документ¶

name: "Мои стандарты"
version: "1.0.0"

rules:
  - id: "CUSTOM-001"
    title: "Избегать магических чисел"
    category: style
    severity: warning
    pattern: "\\b\\d{3,}\\b"
    suggestion: "Выделить в именованную константу"

Полный шаблон документа¶

name: "Полный шаблон стандартов"
version: "1.0.0"
last_updated: "2024-12-09"
author: "Ваша команда"
description: |
  Комплексные стандарты кодирования для проекта.

# Категории, используемые в документе
categories:
  - naming
  - security
  - style
  - documentation
  - error_handling
  - performance

# Глобальная конфигурация
config:
  default_severity: warning
  file_patterns:
    - "*.py"
    - "*.js"
  exclude_patterns:
    - "*_test.py"
    - "test_*.py"

rules:
  - id: "RULE-001"
    title: "Название правила"
    category: security
    severity: error  # error, warning, info
    description: "Подробное описание правила."
    pattern: "regex pattern"  # Опционально: regex для обнаружения
    reference:
      url: "https://example.com/doc"
      document: "Название документа"
      section: "Раздел 3.2"
    suggestion: "Как исправить нарушение"
    examples:
      bad: "Пример нарушения"
      good: "Пример правильного кода"
    tags:
      - "owasp"
      - "critical"

Интеграция с CI/CD¶

# .github/workflows/standards.yml
name: Проверка стандартов
on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Запуск проверки стандартов
        run: |
          codegraph standards import standards.yaml
          codegraph standards check src/ --severity error --exit-code

Связанные сценарии¶

Соответствие - Проверка стандартов кодирования
Редактирование файлов - Применение исправлений
Оптимизация кода - Улучшения с помощью ИИ
Композитные рабочие процессы - Детали оркестрации