Руководство по интеграции внешнего контекста

+-----------------------------------------------------------------+
|                    Внешние системы                                |
+---------------+---------------------+---------------------------+
|    Git        |   Трекеры задач     |        Sentry             |
|  (коммиты)    |  (Jira/GitHub/GL)   |       (ошибки)            |
+-------+-------+----------+----------+-----------+---------------+
        |                  |                      |
        v                  v                      v
+-----------------------------------------------------------------+
|              ExternalContextOrchestrator                         |
|  +---------------+ +-----------------+ +---------------------+  |
|  |GitSyncService | |IssueSyncService | |SentrySyncService    |  |
|  +---------------+ +-----------------+ +---------------------+  |
+-----------------------------------------------------------------+
        |                                          |
        v                                          v
+--------------------+                  +------------------------+
|   PostgreSQL       |                  |      DuckDB CPG        |
| (необработанные    |                  |   (nodes_tag_v2,       |
|  метаданные)       |                  |    edges_tagged_by,    |
| - external_context |                  |    nodes_method)        |
| - file_commit_hist |                  +------------------------+
| - git_authors      |
| - runtime_metrics  |
+--------------------+

pip install -r requirements.txt

# Git (дополнительная настройка не требуется — используется локальный git)

# GitHub Issues
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

# GitLab Issues
export GITLAB_TOKEN="glpat-xxxxxxxxxxxx"

# Jira
export JIRA_TOKEN="your_jira_api_token"

# Sentry
export SENTRY_AUTH_TOKEN="your_sentry_token"

from src.services.external_context import ExternalContextOrchestrator

# Инициализация оркестратора
orchestrator = ExternalContextOrchestrator(
    duckdb_conn=your_duckdb_connection,
    pg_conn=your_postgres_connection,  # необязательно
    repo_path="/path/to/your/repo"
)

# Синхронизация всех источников
result = orchestrator.sync_all(
    git_config={"since_days": 90, "use_blame": True},
    issue_config={
        "provider": "github",
        "repo": "owner/repo",
        "token": os.getenv("GITHUB_TOKEN"),
    },
    sentry_config={
        "org_slug": "my-org",
        "project_slug": "my-project",
        "token": os.getenv("SENTRY_AUTH_TOKEN"),
    },
)

print(f"Всего синхронизировано: {result.total_items_synced}, тегов: {result.total_tags_created}")

from src.services.external_context import GitSyncService

service = GitSyncService(
    duckdb_conn=conn,
    pg_conn=pg_conn,        # необязательно, для хранения необработанных данных
    repo_path="/path/to/repo",
    max_commits=1000,        # по умолчанию
    since_days=90            # по умолчанию
)

# Синхронизация с анализом blame
result = service.sync(use_blame=True)
print(f"Синхронизировано {result.items_synced} коммитов, создано {result.tags_created} тегов")

# Синхронизация только определенных файлов, без blame
result = service.sync(files=["src/main.py", "src/auth.py"], use_blame=False)

-- Найти все методы, измененные конкретным автором
SELECT m.full_name, m.filename, t.value AS author
FROM nodes_method m
JOIN edges_tagged_by e ON m.id = e.src
JOIN nodes_tag_v2 t ON e.dst = t.id
WHERE t.name = 'git-author' AND t.value = 'developer@example.com';

-- Найти код с высокой частотой изменений (методы, измененные > 10 раз)
SELECT m.full_name, CAST(t.value AS INT) AS churn_count
FROM nodes_method m
JOIN edges_tagged_by e ON m.id = e.src
JOIN nodes_tag_v2 t ON e.dst = t.id
WHERE t.name = 'git-churn' AND CAST(t.value AS INT) > 10
ORDER BY churn_count DESC;

-- Найти кандидатов на bus factor (методы с единственным автором)
SELECT m.full_name, t_author.value AS sole_author
FROM nodes_method m
JOIN edges_tagged_by e1 ON m.id = e1.src
JOIN nodes_tag_v2 t_blame ON e1.dst = t_blame.id
JOIN edges_tagged_by e2 ON m.id = e2.src
JOIN nodes_tag_v2 t_author ON e2.dst = t_author.id
WHERE t_blame.name = 'git-blame-count' AND t_blame.value = '1'
  AND t_author.name = 'git-author';

-- Найти недавно измененные методы (за последние 7 дней)
SELECT m.full_name, m.filename, t.value AS last_modified
FROM nodes_method m
JOIN edges_tagged_by e ON m.id = e.src
JOIN nodes_tag_v2 t ON e.dst = t.id
WHERE t.name = 'git-last-modified'
  AND CAST(t.value AS TIMESTAMP) > NOW() - INTERVAL '7 days'
ORDER BY t.value DESC;

from src.services.external_context import IssueSyncService

# GitHub
service = IssueSyncService(
    duckdb_conn=conn,
    pg_conn=pg_conn,
    provider="github",
    repo="owner/repo",
    token=os.getenv("GITHUB_TOKEN"),
    max_issues=500  # по умолчанию
)

# GitLab
service = IssueSyncService(
    duckdb_conn=conn,
    provider="gitlab",
    repo="owner/repo",
    base_url="https://gitlab.company.com",
    token=os.getenv("GITLAB_TOKEN")
)

# Jira
service = IssueSyncService(
    duckdb_conn=conn,
    provider="jira",
    project_key="PROJ",
    base_url="https://company.atlassian.net",
    token=os.getenv("JIRA_TOKEN")
)

result = service.sync(since_days=90, link_via_commits=True)

service = IssueSyncService(
    duckdb_conn=conn,
    provider="jira",
    project_key="PROJ",
    base_url="https://company.atlassian.net",
    token=os.getenv("JIRA_TOKEN")
)

issue_key = service.create_jira_issue(
    summary="Fix NullPointerException in AuthService",
    description="Method authenticate() throws NPE when token is expired",
    issue_type="Bug",        # по умолчанию
    priority="Medium",       # по умолчанию
    labels=["codegraph", "auto-detected"],
    components=["auth"]
)
# Возвращает "PROJ-456" или None в случае ошибки

from src.services.external_context import SentrySyncService

service = SentrySyncService(
    duckdb_conn=conn,
    pg_conn=pg_conn,
    org_slug="my-organization",
    project_slug="my-project",
    token=os.getenv("SENTRY_AUTH_TOKEN"),
    base_url="https://sentry.io",  # по умолчанию; переопределите для self-hosted
    max_issues=200                  # по умолчанию
)

result = service.sync(since_days=30, min_events=1)

-- Найти методы с критической частотой ошибок
SELECT m.full_name, m.filename, t.value AS frequency
FROM nodes_method m
JOIN edges_tagged_by e ON m.id = e.src
JOIN nodes_tag_v2 t ON e.dst = t.id
WHERE t.name = 'error-frequency' AND t.value = 'critical';

-- Найти методы по типу ошибки
SELECT m.full_name, t.value AS error_type
FROM nodes_method m
JOIN edges_tagged_by e ON m.id = e.src
JOIN nodes_tag_v2 t ON e.dst = t.id
WHERE t.name = 'error-type' AND t.value LIKE '%NullPointer%';

-- Комбинация: методы с высокой+ частотой И уровнем fatal
SELECT DISTINCT m.full_name, m.filename
FROM nodes_method m
JOIN edges_tagged_by e1 ON m.id = e1.src
JOIN nodes_tag_v2 t_freq ON e1.dst = t_freq.id
JOIN edges_tagged_by e2 ON m.id = e2.src
JOIN nodes_tag_v2 t_level ON e2.dst = t_level.id
WHERE t_freq.name = 'error-frequency' AND t_freq.value IN ('critical', 'high')
  AND t_level.name = 'error-level' AND t_level.value = 'fatal';

from src.services.external_context import ExternalContextOrchestrator

orchestrator = ExternalContextOrchestrator(
    duckdb_conn=conn,
    pg_conn=pg_conn,       # необязательно
    repo_path=".",
    vector_store=None      # необязательно, для семантического индексирования
)

# Синхронизация всех источников одновременно
result = orchestrator.sync_all(
    git_config={"since_days": 30, "use_blame": True},
    issue_config={
        "provider": "github",
        "repo": "owner/repo",
        "token": token,
    },
    sentry_config={
        "org_slug": "org",
        "project_slug": "proj",
        "token": sentry_token,
    },
    parallel=True  # запуск синхронизаций параллельно
)

print(f"Успешно: {result.success}")
print(f"Элементов синхронизировано: {result.total_items_synced}")
print(f"Тегов создано: {result.total_tags_created}")
print(f"Ребер создано: {result.total_edges_created}")
print(f"Длительность: {result.duration_seconds:.1f}s")

# Доступ к результатам по источникам
for source, src_result in result.source_results.items():
    print(f"  {source}: {src_result.items_synced} элементов, {src_result.tags_created} тегов")

# Синхронизация отдельных источников
git_result = orchestrator.sync_git(since_days=30, use_blame=True)
issue_result = orchestrator.sync_issues(
    provider="github", repo="owner/repo", token=token
)
sentry_result = orchestrator.sync_sentry(
    org_slug="org", project_slug="proj", token=token
)

# Получение статистики синхронизации
stats = orchestrator.get_sync_stats()

# Синхронизация истории Git
python -m src.services.external_context.orchestrator \
    --duckdb /path/to/cpg.duckdb \
    --repo-path /path/to/repo \
    --sync-git --git-since-days 30

# Синхронизация Git без анализа blame
python -m src.services.external_context.orchestrator \
    --duckdb /path/to/cpg.duckdb \
    --sync-git --no-blame

# Синхронизация Git с ограничением числа коммитов
python -m src.services.external_context.orchestrator \
    --duckdb /path/to/cpg.duckdb \
    --sync-git --git-max-commits 2000

# Синхронизация задач GitHub
python -m src.services.external_context.orchestrator \
    --duckdb /path/to/cpg.duckdb \
    --sync-issues --issue-provider github --issue-repo owner/repo \
    --issue-token "$GITHUB_TOKEN"

# Синхронизация задач GitLab (self-hosted)
python -m src.services.external_context.orchestrator \
    --duckdb /path/to/cpg.duckdb \
    --sync-issues --issue-provider gitlab --issue-repo owner/repo \
    --issue-url https://gitlab.company.com \
    --issue-token "$GITLAB_TOKEN"

# Синхронизация задач Jira
python -m src.services.external_context.orchestrator \
    --duckdb /path/to/cpg.duckdb \
    --sync-issues --issue-provider jira --issue-project PROJ \
    --issue-url https://company.atlassian.net \
    --issue-token "$JIRA_TOKEN"

# Синхронизация ошибок Sentry
python -m src.services.external_context.orchestrator \
    --duckdb /path/to/cpg.duckdb \
    --sync-sentry --sentry-org my-org --sentry-project my-project \
    --sentry-token "$SENTRY_AUTH_TOKEN"

# Синхронизация Sentry (self-hosted)
python -m src.services.external_context.orchestrator \
    --duckdb /path/to/cpg.duckdb \
    --sync-sentry --sentry-org my-org --sentry-project my-project \
    --sentry-token "$SENTRY_AUTH_TOKEN" --sentry-url https://sentry.company.com

# Синхронизация всех источников
python -m src.services.external_context.orchestrator \
    --duckdb /path/to/cpg.duckdb \
    --repo-path /path/to/repo \
    --sync-all

# Просмотр статистики синхронизации
python -m src.services.external_context.orchestrator \
    --duckdb /path/to/cpg.duckdb --stats

# Подробный вывод
python -m src.services.external_context.orchestrator \
    --duckdb /path/to/cpg.duckdb --sync-git --verbose

from src.services.external_context import (
    sync_git_to_cpg,
    sync_issues_to_cpg,
    sync_sentry_to_cpg,
)

# Синхронизация метаданных Git
result = sync_git_to_cpg(
    duckdb_conn=conn,
    pg_conn=pg_conn,       # необязательно
    repo_path=".",
    since_days=30,
    use_blame=True
)

# Синхронизация задач
result = sync_issues_to_cpg(
    duckdb_conn=conn,
    pg_conn=pg_conn,
    provider="github",
    repo="owner/repo",
    token=os.getenv("GITHUB_TOKEN")
)

# Синхронизация ошибок Sentry
result = sync_sentry_to_cpg(
    duckdb_conn=conn,
    pg_conn=pg_conn,
    org_slug="my-org",
    project_slug="my-project",
    token=os.getenv("SENTRY_AUTH_TOKEN")
)

class ExternalContextBase(ABC):
    def __init__(self, duckdb_conn, pg_conn=None, source: ExternalSource = None):
        ...

# Проверка доступности истории Git
python -m src.services.external_context.orchestrator \
    --duckdb /path/to/cpg.duckdb \
    --sync-git --git-since-days 7 --verbose

# Пропуск blame при работе с большими репозиториями
python -m src.services.external_context.orchestrator \
    --duckdb /path/to/cpg.duckdb \
    --sync-git --no-blame

service = IssueSyncService(
    duckdb_conn=conn,
    provider="github",
    repo="owner/repo",
    token=os.getenv("GITHUB_TOKEN")
)

-- Просмотр значений тегов
SELECT name, value, COUNT(*) FROM nodes_tag_v2 GROUP BY name, value LIMIT 20;

-- Проверка количества ребер
SELECT COUNT(*) FROM edges_tagged_by;