Часто задаваемые вопросы

Здесь собраны короткие, но предметные ответы по архитектуре, подсистемам и рабочим сценариям CodeGraph и GoCPG.

Содержание

Оркестрация и маршрутизация

Как работает оркестрация сценариев?

Оркестрация построена на графе LangGraph с тремя основными этапами: classify_intent_node → pre_retrieval → route_by_intent. Класс MultiScenarioCopilot (src/workflow/orchestration/copilot.py) собирает этот граф и запускает его через run(query). Сначала определяется тип запроса, затем при необходимости подгружается контекст, после чего запрос направляется в один из 21 сценариев.

Какие сценарии поддерживает система?

Система поддерживает 21 сценарий: S01 (онбординг), S02 (безопасность), S03 (документация), S04 (разработка фич), S05 (рефакторинг), S06 (производительность), S07 (покрытие тестами), S08 (соответствие требованиям), S09 (ревью кода), S10 (кросс-репозиторный анализ), S11 (архитектура), S12 (технический долг), S13 (массовый рефакторинг), S14 (инциденты безопасности), S15 (отладка), S16 (точки входа), S17 (редактирование файлов), S18 (оптимизация кода — композитный), S19 (проверка стандартов — композитный), S20 (зависимости), S21 (структурный поиск паттернов).

Что такое route_by_intent и как он работает?

Функция route_by_intent (src/workflow/orchestration/router.py:16) принимает состояние MultiScenarioState с полем intent (заполненным на этапе классификации) и возвращает имя следующего узла рабочего процесса. Внутри используется словарь routing_map, который отображает значения intent на имена функций-обработчиков (например, "onboarding" → "onboarding_workflow", "tech_debt" → "tech_debt_workflow"). Поддерживает составной режим для комплексных запросов.

Что такое MultiScenarioCopilot?

MultiScenarioCopilot (src/workflow/orchestration/copilot.py) — центральный оркестратор системы. Он строит LangGraph-граф, запускает классификацию намерения и маршрутизацию, а затем передаёт управление соответствующему обработчику сценария. Метод run(query) возвращает словарь состояния с полями query, intent, scenario_id, confidence, answer, evidence и metadata.

Что такое classify_intent_node?

Узел classify_intent_node (src/workflow/orchestration/intent.py) выполняет LLM-классификацию намерения пользователя. На вход получает текст запроса, на выходе заполняет поля intent, scenario_id и confidence в состоянии MultiScenarioState. Использует промпт из config/prompts/{lang}/workflow_prompts.yaml с перечнем всех сценариев.

Что такое pre_retrieval узел?

Узел pre_retrieval (src/workflow/orchestration/pre_retrieval.py) — необязательный этап между классификацией и маршрутизацией (фаза E). Выполняет HybridRetriever.retrieve() для предварительного получения контекста из ChromaDB и DuckDB. Результаты сохраняются в state["pre_retrieval_results"]. Включается через config.yaml → workflows.pre_retrieval.enable: true (включён по умолчанию).

Авторизация и безопасность

Как устроена авторизация в API?

Авторизация реализована через несколько механизмов: JWT-токены, API-ключи и OAuth 2.0. Центральная зависимость FastAPI — get_auth_context (src/api/auth/middleware.py) — извлекает и валидирует данные пользователя из каждого входящего запроса. Результат помещается в AuthContext — контейнер с полями user_id, username, role, scopes и auth_method.

Как работает проверка прав доступа?

Функция has_permission (src/api/auth/middleware.py) проверяет, имеет ли пользователь конкретное разрешение на основе его роли (VIEWER, ANALYST, REVIEWER, ADMIN). Роли и разрешения определены в src/api/database/models.py. Система использует RBAC (Role-Based Access Control) с возможностью расширения через области видимости (scopes).

Какие OAuth-провайдеры поддерживаются?

Поддерживаются два OAuth-провайдера: SourceCraft (через Yandex ID, SourceCraftOAuth в src/api/auth/oauth.py) и GitVerse (через Sber ID, GitVerseOAuth). Оба наследуют общий интерфейс и поддерживают get_authorization_url(), exchange_code() и get_user_info().

Как работает аутентификация в MCP-сервере?

MCP-сервер (src/mcp/auth.py) поддерживает Bearer JWT и API-ключи для SSE/HTTP-транспортов. Для stdio-транспорта аутентификация не требуется. Флаг --no-auth отключает проверку для разработки.

Какие механизмы защиты от атак реализованы?

Система включает: нейтрализацию путей (db_path из тела запроса игнорируется), защиту от IDOR (проверка owner_user_id), replay-защиту webhook’ов (проверка временных меток), CSRF-защиту OAuth (одноразовые state-токены), ограничение частоты запросов (трёхуровневый rate limiter), валидацию сложности SQL-запросов и DLP-фильтрацию.

Как работает блокировка токенов?

Функция is_token_blacklisted проверяет, не был ли JWT-токен отозван. Чёрный список синхронизируется через _blacklist_sync_task() с настраиваемым интервалом (security.token_blacklist_sync_interval_seconds). Отозванные токены блокируются до истечения срока действия.

Граф свойств кода (CPG)

Что такое граф свойств кода (CPG)?

CPG (Code Property Graph) — объединённое представление исходного кода в виде графа, содержащего абстрактное синтаксическое дерево (AST), граф потока управления (CFG) и граф потока данных (DFG). В CodeGraph CPG хранится в DuckDB и содержит таблицы nodes_method, nodes_type, edges_call, call_containment, edges_inherits_from и другие.

Как устроен CPGQueryService?

CPGQueryService (src/services/cpg/) — основной клиент для работы с CPG через DuckDB. Построен на паттерне миксинов: базовый класс CPGQueryBase (src/services/cpg/base.py) плюс 11 миксинов запросов (SubsystemQueries, CallGraph, Security, Performance, Quality, Semantic, Statistics, Comment, External, Type, Pattern). Путь к БД определяется через ProjectManager.get_active_db_path().

Что такое call_containment?

Представление (view) call_containment в DuckDB связывает вызовы функций с содержащими их методами. Поля: containing_method_name (вызывающий метод) и callee_name (вызываемый метод). Используется для построения графа вызовов в MechanismExplanationHandler.

Что означает поле is_test в nodes_method?

Булево поле is_test указывает, является ли метод тестовым (определяется GoCPG по именованию и расположению). Используется для фильтрации тестовых функций из результатов анализа при нетестовых запросах.

GoCPG — генератор CPG

Что такое GoCPG?

GoCPG (gocpg/) — генератор графа свойств кода, написанный на Go. Поддерживает 11 языков программирования: C, C++, Go, Python, JavaScript, TypeScript, Java, Kotlin, C#, PHP и 1С:Предприятие. Использует tree-sitter для парсинга, требует CGO_ENABLED=1.

Как запустить GoCPG?

cd gocpg
CGO_ENABLED=1 go build -o gocpg.exe ./cmd/gocpg  # Сборка
./gocpg parse --input=/path/to/source --output=out.duckdb --lang=python  # Парсинг
./gocpg stats --db=out.duckdb  # Статистика
./gocpg query --db=out.duckdb --sql="SELECT COUNT(*) FROM nodes_method"  # Запрос
./gocpg serve --port 50051 --data-dir ./data/projects  # gRPC-сервер

Как GoCPG интегрируется с Python?

Python-клиент (src/services/gocpg/) поддерживает два транспорта: gRPC (grpc_transport.py) и subprocess. Конфигурация transport ("auto", "grpc", "subprocess") определяет режим. В режиме "auto" сначала пробуется gRPC, затем subprocess.

Какие таблицы создаёт GoCPG?

GoCPG создаёт 43 таблицы узлов, 25 таблиц рёбер, 2 представления и несколько служебных таблиц. Ключевые: nodes_method (методы/функции), nodes_call (точки вызова), nodes_type_decl (объявления типов), nodes_file (файлы), edges_call (рёбра вызовов), edges_ast (структура AST), edges_cfg (поток управления), edges_reaching_def (достигающие определения потока данных), edges_inherits_from (наследование). Представления: call_containment (денормализованные вызывающий/вызываемый) и method_docstrings. Состояние: cpg_git_state, cpg_file_state, cpg_fqn_index. Полная схема в docs/reference/ru/SCHEMA.md.

Что такое конвейер проходов GoCPG?

GoCPG выполняет 31 аналитический проход в порядке DAG (направленного ациклического графа): базовые (MetaData, File, Namespace) → типы (TypeNode, TypeDecl, Inheritance) → CFG/Dominator/CDG → разрешение вызовов (CallGraph, CallResolution) → поток данных (Ref, AliasAnalysis, ReachingDef, InterproceduralReachingDef) → PDG/DDG → обогащение (MethodMetrics, FindingGeneration, PatternMatch). Каждый проход читает CPGGraph (в памяти), пишет DiffGraph, никогда не обращается к DuckDB напрямую.

Что такое инкрементальное обновление в GoCPG?

GoCPG поддерживает git-инкрементальное обновление через gocpg update или gocpg ci-update. Сравнивает хеши файлов в cpg_file_state с рабочим деревом, повторно парсит только изменённые файлы и перестраивает затронутые аналитические проходы. Для CI флаг --base-ref ограничивает анализ файлами, изменёнными с указанной git-ссылки. Откат к полному перепарсингу при превышении --incremental-threshold (по умолчанию: 30 файлов).

Что такое TKB (Type Knowledge Base)?

TKB — база знаний типов в формате YAML (gocpg/configs/typestubs/), содержащая 46 файлов для 11 языков. Предоставляет информацию о возвращаемых типах стандартных библиотечных функций без анализа исходного кода.

Гибридный поиск и извлечение

Как работает гибридный поиск?

HybridRetriever (src/retrieval/hybrid/retriever.py) выполняет параллельный поиск по ChromaDB (векторный) и DuckDB (графовый), затем объединяет результаты через адаптивный RRF (Reciprocal Rank Fusion). Веса зависят от типа запроса: семантический (75% вектор / 25% граф), структурный (25% / 75%), безопасность (40% / 60%), по умолчанию (60% / 40%).

Что хранится в ChromaDB?

ChromaDB содержит несколько коллекций: code_comments (документация и комментарии кода), code_snippets (фрагменты кода) и domain_patterns (доменные паттерны). Коллекции изолированы по проектам через префикс имени (например, codegraph_code_comments). Индексация выполняется скриптом scripts/index_codegraph_vectors.py.

Что такое фаза Pre-Retrieval (Phase E)?

Узел pre_retrieval в LangGraph-графе (src/workflow/orchestration/pre_retrieval.py) запускает HybridRetriever между классификацией намерения и маршрутизацией. Результаты сохраняются в state["pre_retrieval_results"] и доступны всем обработчикам сценариев. Включён по умолчанию (config.yaml → workflows.pre_retrieval.enable: true).

Как работает RRF-слияние?

RRF (Reciprocal Rank Fusion) — метод слияния ранжированных списков. Для каждого документа вычисляется score = Σ (weight / (k + rank_i)), где k — константа сглаживания, rank_i — позиция в i-м списке, weight — вес источника. Результаты сортируются по итоговому score. Реализация в src/retrieval/hybrid/merger.py.

Конфигурация и настройка

Что такое get_unified_config?

Функция get_unified_config() (src/config/unified_config.py) — единая точка доступа к конфигурации. Возвращает Pydantic-объект UnifiedConfig, загруженный из config.yaml при первом вызове (паттерн singleton через get_instance()). Доступ к значениям через атрибуты: config.llm.provider, config.timeouts.global_query_timeout, config.reranking.boost_domain_match.

Какие секции есть в config.yaml?

Основные секции: llm (провайдер и настройки LLM), api (порт, аутентификация, демо-режим), workflows (настройки сценариев, пре-ретривал, обогащение), security (rate limit, DLP, CSP), composition (композитные оркестраторы), timeouts (таймауты сервисов), projects (реестр проектов), domain (активный домен).

Как настроить LLM-провайдер?

В config.yaml → llm.provider установите yandex, gigachat, openai или local. Переменные окружения: YANDEX_API_KEY/YANDEX_FOLDER_ID для Yandex AI, GIGACHAT_AUTH_KEY для GigaChat, OPENAI_API_KEY для OpenAI. Для локального Qwen3: QWEN3_MODEL_PATH.

Как переключить активный проект?

Проекты регистрируются в config.yaml → projects.registry или в файле projects.yaml. Активный проект задаётся через projects.active. При переключении автоматически активируется доменный плагин проекта через DomainRegistry.activate().

Импорт проектов

Как импортировать проект?

python -m src.cli import /path/to/source --language python

Или программно:

from src.project_import import import_project
result = await import_project(repo_url="https://...", language="python")

Какие этапы включает импорт?

Полный конвейер (src/project_import/pipeline.py): CloneStep → DetectLanguageStep → GoCPGParseStep → ValidateStep → ChromaDBSyncStep → DocGenerationStep → VectorIndexStep → DomainSetupStep. Инкрементальный (при наличии БД): GoCPGUpdateStep → ValidateStep → ChromaDBSyncStep → DomainSetupStep. Автоматически определяется по наличию таблицы cpg_git_state. DocGenerationStep автоматически генерирует документацию из CPG, если каталог docs/ отсутствует.

Как обновить индексы ChromaDB?

python scripts/index_codegraph_vectors.py

Скрипт индексирует код (сниппеты) и документацию (Q&A пары) в коллекции ChromaDB. При обновлении документации рекомендуется переиндексировать для актуализации контекста обогащения.

Обогащение ответов

Как работает обогащение (enrichment)?

Обогащение (src/workflow/scenarios/onboarding/enrichment.py) выполняется в три фазы: 1. Фаза 1 — извлечение описаний из CPG-комментариев (docstring’и и аннотации) 2. Фаза 2 — получение контекста из ChromaDB: Q&A пары (code_comments), примеры кода (code_snippets) 3. Фаза 3 — LLM-синтез: промпт объединяет исходный ответ, CPG-описания, вектор-контекст и генерирует обогащённый ответ

Можно ли отключить LLM-обогащение?

Да, через config.yaml → workflows.onboarding.enrichment.enable: false. Также обработчики могут устанавливать skip_enrichment=True на OnboardingResult для структурированных ответов (таблицы, списки), чтобы LLM не переписывал их.

Какие параметры LLM используются при обогащении?

llm_max_tokens и llm_temperature задаются в config.yaml → workflows.onboarding.enrichment. Токены масштабируются адаптивно: max(base_max_tokens, len(original_answer) // 3 + 200) для предотвращения обрезки длинных ответов. По умолчанию: llm_max_tokens: 1000, llm_temperature: 0.3.

Что такое _has_rich_structure?

Функция _has_rich_structure() определяет, содержит ли ответ структурированное форматирование (заголовки ##, call chain, списки вызывающих/вызываемых). Для таких ответов фаза 1 (CPG comments) пропускает переформатирование через DefinitionFormatter, сохраняя исходную структуру.

Сценарные рабочие процессы

Как устроен обработчик рабочего процесса?

Каждый сценарий реализован как функция {name}_workflow(state: MultiScenarioState) -> MultiScenarioState. Обработчик получает состояние с запросом, результатами предварительного поиска и метаданными, выполняет анализ через CPG и/или LLM и заполняет поля answer, evidence, metadata.

Что такое составные рабочие процессы?

Составные рабочие процессы оркестрируют несколько подсценариев: S18 (оптимизация кода) запускает S02, S05, S06, S11, S12 параллельно (таймаут 60 с), S19 (проверка стандартов) — S08, S17, S18 последовательно (45 с), а аудит — 9 подсценариев параллельно (600 с). Конфликты разрешаются по приоритету с повышающим коэффициентом для безопасности (1.5x) и соответствия требованиям (1.3x).

Какой базовый класс использовать для обработчика?

Все обработчики сценариев наследуют от BaseHandler (src/workflow/scenarios/_base/handler.py). Не используйте AnalysisHandler (src/workflow/handlers/analysis.py) — его конструктор несовместим с реестром сценариев.

Как устроена онбординг-обработка (S01)?

onboarding_workflow (src/workflow/scenarios/onboarding/workflow.py) использует реестр обработчиков OnboardingHandlerRegistry. Функция detect_onboarding_query_type() определяет тип запроса (определение, граф вызовов, механизм, подсистема и т.д.) и выбирает обработчик. Поддерживаемые типы: definition, call_graph, mechanism_explain, subsystem, file_structure, key_functions, metrics.

Мультитенантность и API

Как работает мультитенантность?

При multi_tenant.enabled: true API изолирован по заголовку X-Project-Id. ProjectContext — замороженный dataclass с полями project_id, group_id, db_path, domain, language, collection_prefix. ProjectScopedServices кеширует экземпляры CPGQueryService и VectorStore по ключу db_path/collection_prefix.

Как защищён путь к базе данных?

Все API-роутеры используют ctx.db_path из ProjectContext. Пользовательский db_path из тела запроса или query-параметров игнорируется с предупреждением о deprecation. Экземпляры CPGQueryBase принимают allowed_db_paths — проверка выполняется при каждом запросе.

Какие интерфейсы доступа есть?

Четыре уровня доступа: CLI (python -m src.cli), REST API (/api/v1/), MCP-сервер (python -m src.mcp), ACP-протокол (src/acp/). REST API документирован по адресу http://localhost:8000/api/docs.

Как работает демо-режим?

При api.demo.enabled: true конечная точка /api/v1/demo/chat доступна без аутентификации. Она принимает {"query": "..."}, выполняет полный конвейер (классификация → обработка → обогащение) и возвращает {"answer": "...", "scenario_id": "...", "processing_time_ms": ...}.

Модули анализа

Какие модули анализа доступны?

CodeGraph включает несколько модулей анализа в src/analysis/: - Обнаружение клонов (clone_detector.py) — поиск дублированного кода по 4 типам клонов - Анализ помеченных данных (dataflow/taint_analysis.py) — отслеживание распространения ненадёжных данных - Символьное выполнение (dataflow/symbolic_execution.py) — проверка достижимости путей через Z3 - Обнаружение состояний гонки (race_detector.py) — поиск TOCTOU и проблем синхронизации - Анализ параллелизма (concurrency_analyzer.py) — обнаружение взаимоблокировок и нарушений порядка блокировок - Маппинг соответствия (compliance.py) — сопоставление находок с CWE, OWASP, CERT, MISRA - Анализ графа вызовов (callgraph/) — PageRank, SCC, betweenness centrality, поиск путей - Движок автоисправлений (autofix/) — генерация исправлений уязвимостей на основе шаблонов и LLM

Как работает обнаружение клонов?

ASTCloneDetector (src/analysis/clone_detector.py) попарно сравнивает методы по 4 метрикам сходства: Жаккар по токенам (>0.95 → Тип 1, точный), нормализованные токены (>0.85 → Тип 2, переименованный), структура AST (>0.75 → Тип 3, структурный), поток управления (>0.70 → Тип 4, семантический). Возвращает объекты CloneResult, отсортированные по убыванию сходства. Ограничение по умолчанию: 300 методов (max_methods_extended). См. docs/reference/ru/CLONE_DETECTION.md.

Как работает анализ помеченных данных?

TaintPropagator (src/analysis/dataflow/taint_analysis.py) отслеживает поток ненадёжных данных через CPG, используя edges_reaching_def и edges_call. Источники и стоки определяются доменным плагином (get_taint_sources(), get_taint_sinks()). Использует чувствительный к полям и межпроцедурный анализ. Интегрируется с PathConstraintTracker для символьной проверки достижимости путей через Z3. См. docs/reference/ru/SYMBOLIC_EXECUTION.md.

Как работает движок автоисправлений?

Движок автоисправлений (src/analysis/autofix/) генерирует предложения по исправлению обнаруженных уязвимостей. Читает исходный файл, сопоставляет уязвимость с идентификатором CWE, выбирает шаблон исправления или генерирует патч с помощью LLM, валидирует diff и выдаёт унифицированный diff. Поддерживает как шаблонную (детерминированную), так и LLM-генерацию (креативную).

Как определяются мёртвые методы?

Мёртвые методы определяются через AuditRunner._collect_metrics() с многоуровневой фильтрацией ложных срабатываний: фильтр is_test (V25), class-aware достижимость (V26), наследование (V26b), вложенные функции (V27), полностью мёртвые модули (V28), модули с низкой витальностью (V29), companion-файлы (V30). GoCPG создаёт синтетические рёбра CALL для реэкспортов из __init__.py, callable-аргументов (callback=fn) и паттернов регистрации фреймворков (LangGraph add_node, FastAPI include_router).

Система гипотез безопасности

Что такое система гипотез безопасности?

Система гипотез (src/security/hypothesis/) — движок многокритериального обнаружения уязвимостей. Объединяет базу знаний (58 записей CWE, 27 записей CAPEC, 13 шаблонов обнаружения) с анализом CPG. Генерирует гипотезы о потенциальных уязвимостях, синтезирует DuckDB/PGQ-запросы для их проверки и оценивает результаты через многокритериальный скорер.

Как работает генерация гипотез?

HypothesisExecutor (src/security/hypothesis/executor.py) принимает запрос по безопасности (например, «SQL-инъекция в обработке пользовательского ввода») и: (1) сопоставляет с базами знаний CWE/CAPEC, (2) выбирает применимые шаблоны обнаружения, (3) синтезирует CPG-запросы, нацеленные на паттерн уязвимости, (4) выполняет запросы к DuckDB проекта, (5) оценивает находки через многокритериальный скорер, (6) возвращает ранжированные гипотезы с доказательствами.

Что такое провайдеры гипотез?

Провайдеры предоставляют доменно-специфичные паттерны уязвимостей. Встроенные провайдеры существуют для PostgreSQL, Django, Express, Spring, Gin и Next.js (src/security/hypothesis/{framework}/). YAML-провайдер (providers/yaml_provider.py) позволяет определять пользовательские паттерны. Провайдеры автоматически обнаруживаются на основе активного доменного плагина.

Как работает многокритериальный скорер?

MultiCriteriaScorer (src/security/hypothesis/multi_criteria_scorer.py) оценивает гипотезы по нескольким измерениям: достижимость потока данных, контекст кода, фреймворк-специфичные паттерны и историческая обратная связь. Доступны три пресета: embedded (строгий, для критически важных систем), web (сбалансированный, для веб-приложений) и enterprise (ориентированный на соответствие требованиям). Каждый пресет регулирует распределение весов между критериями оценки.

Как работает цикл обратной связи?

FeedbackStore (src/security/hypothesis/feedback.py) отслеживает решения аналитика (подтверждено/ложное срабатывание/отложено) по гипотезам. TrendStore (src/security/hypothesis/trend_store.py) агрегирует обратную связь для выявления повторяющихся паттернов. Это снижает количество ложных срабатываний в последующих запусках и помогает калибровать многокритериальный скорер.

Генерация документации и журнала изменений

Как работает генерация документации?

DocumentationGenerator (src/services/doc_generator.py) автоматически генерирует 8 разделов документации из данных CPG: обзор проекта (MVD), обзор модулей, документация функций, документация конвейеров, описание бизнес-логики, документация типов, отчёты покрытия и диаграммы графа вызовов. Результат может индексироваться в ChromaDB для векторного поиска.

Как сгенерировать документацию?

python -m src.cli.generate_docs full --output ./docs/generated --language ru
python -m src.cli.generate_docs full --output ./docs/generated --language en  # Английский
python -m src.cli.generate_docs --sections overview,functions --output ./docs/generated

Или через MCP: codegraph_reindex action=generate. При импорте проекта DocGenerationStep запускается автоматически, если в проекте нет каталога docs/.

Как работает генерация журнала изменений?

ChangelogGenerator (src/changelog/generator.py) разбирает git-историю на конвенциональные коммиты (feat:, fix:, docs: и т.д.), извлекает область действия и маркеры критических изменений, группирует изменения по типу, разрешает ссылки на задачи и генерирует структурированный Markdown-журнал. Поддерживает LLM-обогащение для более описательных записей и двуязычный вывод (EN/RU).

Как сгенерировать журнал изменений?

python -m src.cli.changelog_commands --from v1.0.0 --to HEAD
python -m src.cli.changelog_commands --from v1.0.0 --to HEAD --language ru --enhance

Или через REST API: POST /api/v1/changelog/generate с телом {"from_ref": "v1.0.0", "to_ref": "HEAD"}.

Как работает переиндексация векторов?

VectorIndexer (src/retrieval/vector_indexer.py) индексирует данные проекта в 6 коллекций ChromaDB: code_snippets, qa_pairs, documentation, sql_examples, code_comments и domain_patterns. Поддерживает инкрементальную индексацию через отслеживание состояния файлов. CLI: python -m src.cli.reindex_commands reindex [--generate] [--sections ...]. MCP: codegraph_reindex action=reindex.

Доменные плагины

Что такое доменный плагин?

Доменный плагин (DomainPluginV3) предоставляет доменно-специфичные знания для языка программирования или фреймворка. Каждый плагин определяет: имена модулей/подсистем, источники и стоки помеченных данных, категории операций, паттерны безопасности, правила качества кода и доменные промпты. Конфигурируется через 10 YAML-файлов в src/domains/{name}/config/.

Какие домены доступны?

13 доменов: python_generic (по умолчанию), python_django, java, csharp, go, javascript, kotlin, php, postgresql, cpp, bsl_1c, typescript, web. Активный домен задаётся в config.yaml → domain.name или в реестре проектов для каждого проекта отдельно.

Как работает автоматическое определение домена?

CPGConfigLoader (src/config/cpg_config.py) использует эвристику на основе расширений файлов из CPG для определения основного языка проекта. При переключении проекта через ProjectManager.switch_project() соответствующий доменный плагин автоматически активируется через DomainRegistry.activate().

Как создать собственный доменный плагин?

Создайте каталог src/domains/{name}/ с классом плагина, наследующим DomainPluginV3, и 10 YAML-файлами конфигурации: modules.yaml, subsystems.yaml, taint_sources.yaml, taint_sinks.yaml, operation_categories.yaml, security_patterns.yaml, quality_rules.yaml, prompts.yaml, domain_config.yaml, compliance_mapping.yaml. Зарегистрируйте плагин в реестре доменов.

Движок паттернов

Что такое движок паттернов?

Движок паттернов GoCPG (gocpg/pkg/patterns/) обеспечивает структурный поиск кода с семантическими ограничениями. Работает в 4 фазы: (1) Структурный — сопоставление CST через tree-sitter с метапеременными ($VAR, $$$VARS, $_), (2) Ограничения CPG — фильтры по потоку данных, контексту вызовов, типам и метрикам, (3) Инкрементальный — отслеживание зависимостей для эффективного повторного анализа, (4) Перезапись — автоисправление на основе шаблонов с подстановкой метапеременных.

Как искать паттерны?

# Структурный поиск (CPG не нужен)
gocpg search --pattern "malloc($SIZE)" --lang c --input /path/to/source

# Сканирование с учётом CPG и правил
gocpg scan --db=out.duckdb --rules=configs/rules/common/
gocpg scan --db=out.duckdb --domain=postgresql --format sarif

# С автоисправлением
gocpg scan --db=out.duckdb --rules=configs/rules/ --fix --input=./src --dry-run

Как определяются правила паттернов?

Правила описываются в YAML-файлах в configs/rules/ (190 правил в 14 каталогах):

id: rule-id
message: "Описание с $VAR"
severity: error|warning|info|hint
languages: [c, cpp]
rule:
  pattern: "malloc($SIZE)"
fix: "safe_malloc($SIZE)"          # Шаблон автоисправления (необязательно)
constraints: { SIZE: { regex: "^[a-z]" } }
cpg:
  dataflow: { from: "$SRC", to: "$SINK" }
  metrics: { cyclomatic_complexity: ">10" }

Может ли LLM генерировать правила паттернов?

Да. LLMPatternGenerator (src/analysis/patterns/llm_pattern_generator.py) преобразует описание на естественном языке в YAML-правила паттернов. Автоматически валидирует сгенерированные правила через gocpg validate-rule и повторяет попытку при ошибке. Системные промпты загружаются из двуязычных YAML-файлов.

MCP-сервер и инструменты

Что такое MCP-сервер?

MCP-сервер (Model Context Protocol, src/mcp/) предоставляет функциональность CodeGraph для AI-ассистентов. Поддерживает 21 встроенный инструмент плюс динамические SQL-инструменты, загружаемые из .codegraph/tools.yaml. Транспорты: stdio (по умолчанию), SSE и HTTP.

Как запустить MCP-сервер?

python -m src.mcp                              # stdio (по умолчанию)
python -m src.mcp --transport sse --port 27495  # SSE
python -m src.mcp --transport http --port 27495 # HTTP
python -m src.mcp --no-auth                     # Отключить аутентификацию (только для разработки)

Какие MCP-инструменты доступны?

Ключевые инструменты: codegraph_query (запрос на естественном языке), codegraph_search (поиск кода), codegraph_callgraph (анализ графа вызовов), codegraph_hotspots (горячие точки сложности), codegraph_security (анализ безопасности), codegraph_patterns (сканирование паттернов), codegraph_compliance (проверка соответствия), codegraph_tech_debt (анализ технического долга), codegraph_explain (объяснение кода), codegraph_standards_check (стандарты кодирования), codegraph_reindex (переиндексация векторов), codegraph_hypothesis (гипотезы безопасности), codegraph_docs_sync (обнаружение рассинхронизации документации).

Что такое динамические SQL-инструменты?

Динамические SQL-инструменты определяются в .codegraph/tools.yaml для каждого проекта. Каждый инструмент задаёт имя, описание, шаблон SQL-запроса и параметры. MCP-сервер загружает их при запуске и предоставляет наряду со встроенными инструментами. Это позволяет создавать проектно-специфичные CPG-запросы без изменения кода.

Что такое инструмент синхронизации документации интерфейсов?

codegraph_docs_sync запускает 5-фазный композитный сценарий синхронизации документации интерфейсов (src/workflow/scenarios/interface_docs_sync_composite.py): Обнаружение → Разбор документации → Генерация → Обнаружение рассинхронизации → Отчёт. Проверяет 6 интерфейсов (REST API, CLI, MCP, ACP, gRPC, WebSocket) на соответствие их документации и сообщает типы рассинхронизации: UNDOCUMENTED, STALE, OUTDATED, COVERED.