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

Проверьте выбранные исходники по правилам кодирования своего проекта. Сценарий 19 находит совпадения с импортированными правилами и показывает их расположение в коде. По отчёту рецензент выбирает необходимые исправления.

Полный пример проверки

Подготовьте Python-окружение проекта по руководству CLI. Работайте в PowerShell из корня репозитория CodeGraph. Пример проверяет Python-файл по одному явно заданному регулярному выражению в одном процессе.

Сохраните документ правил в standards.yaml:

metadata:
  name: Example logging rules
  version: "1.0"
  language: python
rules:
  - id: LOG-001
    title: Use the configured logger
    description: Find print calls for review.
    category: best_practice
    severity: warning
    language: python
    pattern: '\bprint\s*\('

Сохраните исходный файл в example.py:

def greet(name):
    message = f"Hello, {name}"
    print(message)

Сохраните программу проверки в check_standards_example.py:

import json
from pathlib import Path
from src.standards import StandardsParser, RuleDatabase, StandardsAnalyzer

parser = StandardsParser()
document = parser.parse_file("standards.yaml")
errors = parser.validate_document(document)
if errors:
    raise ValueError("; ".join(errors))
database = RuleDatabase()
database.add_document(document)
rules = database.list_rules(language="python")
if not rules:
    raise ValueError("The document contains no Python rules")
violations = StandardsAnalyzer().analyze_file("example.py", rules)
report = [violation.to_dict() for violation in violations]
Path("violations.json").write_text(
    json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8"
)
print(json.dumps({"rules": len(rules), "violations": len(report)}))

Запустите проверку и прочитайте отчёт:

python check_standards_example.py
Get-Content violations.json -Raw | ConvertFrom-Json | ForEach-Object { $_ | Select-Object rule_id, severity, line_number }

Программа выводит {"rules": 1, "violations": 1}. Отчёт содержит rule_id="LOG-001", severity="warning" и line_number=3: вызов print совпал с правилом. Анализатор читает исходник, а программа записывает violations.json.

Замените содержимое example.py на следующий вариант и повторите те же две команды:

import logging

def greet(name):
    logging.getLogger(__name__).info("Hello, %s", name)

Повторный запуск выводит {"rules": 1, "violations": 0} и записывает [] в violations.json. Правило находит вызовы для ревью. При принятии исправления учитывайте настройку логирования и требования своего проекта.

StandardsParser читает YAML, RuleDatabase хранит документ и правила в текущем процессе, а StandardsAnalyzer возвращает совпадения с расположением в исходнике. Для этого примера нужны Python-окружение и исходные файлы: правило использует регулярное выражение. Правила с CPG-запросом дополнительно требуют настроенного CPG-сервиса.

Доступность CLI

CLI регистрирует команды для импорта стандартов и вывода списков документов и правил, но сейчас они не позволяют загрузить набор правил. Чтобы загрузить YAML и проверить файл, используйте программный пример выше. Он выполняет оба шага в одном процессе.

Статус команды проверки CLI

Команда проверки принимает путь к исходникам и имя отчёта:

python -m src.cli standards check "<source-path>" --output "<violations.json>"

Команда также принимает параметры --document, --category, --severity и --fail-on. Сейчас она останавливается до анализа и не создаёт отчёт. Для проверки файла и сохранения JSON используйте программный пример выше.

Запуск типизированного сценария рецензента

from src.digital_employees.runtime.scenarios import (
    RoleBoundScenarioInvocationRequest,
    invoke_role_bound_scenario_request,
)

request = RoleBoundScenarioInvocationRequest(
    query="Проверь ограниченный компонент по утверждённым стандартам кодирования.",
    employee_id="codegraph_reviewer",
    scenario_id="scenario_19",
    event_type="review_start",
    context={
        "project_key": "codegraph",
        "namespace": "default",
        "task_id": "<task-id>",
        "source_refs": ["<revision-ref>", "<standards-document-ref>"],
        "file_paths": ["<bounded-source-path>"],
    },
)
result = invoke_role_bound_scenario_request(request)
if result.get("error"):
    raise RuntimeError(result["error"])
if not result.get("scenario_id") or not result.get("answer"):
    raise RuntimeError("Scenario returned no scenario identity or answer")
print(result["answer"])

Запрос задаёт проект, ревизию исходников, документ стандартов и файлы для анализа. Результат читайте в result["answer"]. Чтобы сохранить находки в JSON, запустите программную проверку выше.

Другие интерфейсы стандартов

Команда python -m src.cli standards report зарегистрирована, но не формирует отчёт. Сохраните JSON из программного примера выше.

В текущем REST API нет отдельного маршрута для стандартов. Для этой проверки используйте программный пример выше.

Как проверить находки

Для каждого совпадения откройте указанную строку и прочитайте правило. Проверьте, применимо ли оно к этому файлу, и сравните находку с согласованными исключениями. После исправления повторите анализ на той же области. Сохраните ревизию, набор правил, отчёт и решение по каждой находке.

Ошибки и восстановление

Правила не найдены: проверьте список rules и значение language в standards.yaml. Загрузите документ и выполните проверку в том же запуске скрипта.
YAML некорректен: исправьте standards.yaml по сообщению парсера и снова запустите check_standards_example.py.
Неожиданно нет нарушений: проверьте путь исходника, значения rules и language и соответствие шаблона синтаксису исходника.
Команда формирования отчёта завершается с ошибкой: сохраните violations.json из программного примера выше.