Сценарий 19: Проверка по стандартам

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

Обзор¶

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

S19 работает как композитный оркестратор, последовательно вызывая:

Подсценарий	Роль	Обязательность
S08 (Соответствие)	Проверка правил по шаблонам	Обязательный
S17 (Редактирование файлов)	Применение исправлений	Опциональный
S18 (Оптимизация кода)	ИИ-оптимизация исправлений	Опциональный

Конфигурация: config.yaml → composition.orchestrators.scenario_19 (таймаут: 45с, последовательное выполнение).

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

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

CLI¶

# Импортировать документ стандартов
python -m src.cli.import_commands standards import company_standards.yaml

# Список импортированных документов
python -m src.cli.import_commands standards list-documents

# Список правил (с опциональными фильтрами)
python -m src.cli.import_commands standards list-rules --category security

# Проверить код на соответствие стандартам
python -m src.cli.import_commands standards check src/ --severity error

# Удалить импортированный документ
python -m src.cli.import_commands standards delete "Корпоративные стандарты"

MCP (ИИ-ассистент)¶

codegraph_standards_check(query="Проверить стандарты кодирования", category="security", severity="error")

REST API¶

Маршрутизатор стандартов предоставляет 9 эндпоинтов по пути /api/v1/standards/:

Эндпоинт	Метод	Описание
`/import`	POST	Импорт документа стандартов (JSON)
`/import/upload`	POST	Загрузка YAML-файла
`/documents`	GET	Список импортированных документов
`/documents/{id}`	DELETE	Удаление документа
`/rules`	GET	Список правил (фильтрация по категории/серьёзности)
`/analyze`	POST	Анализ кода по стандартам
`/violations`	GET	Получение результатов нарушений
`/report`	POST	Генерация отчёта о нарушениях
`/template`	GET	Получение шаблона 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 │
│                                                            │
╰────────────────────────────────────────────────────────────╯

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

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

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@v4
      - name: Запуск проверки стандартов
        run: |
          python -m src.cli.import_commands standards import standards.yaml
          python -m src.cli.import_commands standards check src/ --severity error --fail-on error

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

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

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

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