# CPG слой: интеграция Joern

Документ фиксирует, **что именно проверено** про Joern применительно к нашему корпусу, и какие выводы из этого следуют для конвейера. Составлен по первоисточникам (исходники `joernio/joern`, официальная документация), а не по памяти: каждый факт помечен уровнем достоверности.

---

## 1. Ключевое открытие, меняющее предусловия

**php2cpg не содержит собственного парсера PHP.** Он вызывает внешний `php` с бандленным `php-parser.phar`.

Подтверждено по исходникам:

- `joern-cli/frontends/php2cpg/README.md`: *«A PHP to CPG converter based on `php-parse`. Requirements: PHP (>=7.0)»*;
- `PhpParser.scala`, метод `phpParseCommand`: `Seq("php", "--php-ini", phpIniPath, phpParserPath) ++ Seq("--with-recovery", "--resolve-names", "--json-dump") ++ filenames`;
- `Php2Cpg.createCpg` → `isPhpVersionSupported` запускает `ExternalCommand.run(Seq("php", "--version"))` и требует **≥ 7.1.0**; иначе `Failure("php not found or version not supported")`.

**Следствие для конвейера:** без `php` в `PATH` фронтенд не деградирует, а **отказывает**. Поэтому в `cpg.py` появилась отдельная проверка `find_php()`, а окружение процесса собирается так, чтобы каталог с `php` был первым в `PATH` — фронтенд вызывает буквально `php`, полный путь к `php.exe` не подходит.

На этой машине: **PHP 8.5 найден** (`C:\tools\php85\php.exe`).

---

## 2. Проверенные факты о структуре и запуске

| Факт | Источник | Уровень |
|---|---|---|
| Фронтенды и их скрипты лежат в `joern-cli/frontends/<имя>/` | `joern-cli/build.sbt`: `frontendMappings("php2cpg", …)` → `ref -> s"frontends/$frontendName/$name"` | подтверждено |
| Утилиты `joern`, `joern-parse`, `joern-export`, `joern-slice` — в `joern-cli/bin/` | механика sbt-native-packager (`JavaAppPackaging`) | вывод, не цитата |
| Язык задаётся `--language PHP` (регистр не важен) | таблица frontends; `buildLanguageList` — «Available languages (case insensitive)» | подтверждено |
| `--frontend-args` передаёт аргументы фронтенду дословно | `CpgBasedTool.scala`: `ARGS_DELIMITER = "--frontend-args"` | подтверждено |
| `--exclude <путь>` исключает файлы (путь относительно входа) | docs.joern.io/frontends/x2cpg | подтверждено |
| Скриптовый режим требует `@main def exec(...)` и `--param k=v` | docs.joern.io/interpreter | подтверждено |
| Результат запроса пишется оператором `#>` в файл | docs.joern.io/shell | подтверждено |
| `PHP_PARSER_BIN` переопределяет путь к парсеру | `PhpParser.scala`: `private val PhpParserBinEnvVar = "PHP_PARSER_BIN"` | подтверждено |
| Фронтенд всегда передаёт `--with-recovery` | `phpParseCommand` | подтверждено |

**Не проверено (требует запуска на распакованном дистрибутиве):**
- точный состав `joern-cli/bin` и наличие `.bat`-двойников;
- наличие флага одиночной команды у `joern` (`-c`/`--command`) — в документации его нет, в конвейер не закладывается;
- поведение `-J-Xmx` именно у `joern-parse.bat`.

---

## 3. Как извлекать данные (проверено по коду экспортёра)

`cpg.bin` — бинарник flatgraph, **из Python напрямую не читается**. Нужен экспорт.

| Что нужно | `--repr` | Совместимые форматы |
|---|---|---|
| CFG / DDG / CDG / PDG | `cfg`/`ddg`/`cdg`/`pdg` | **только `dot`** |
| Весь граф со всеми типами рёбер | `all` | `graphml`, `graphson`, `neo4jcsv`, `dot` |
| Подграф на метод | `cpg` | `graphml`, `graphson`, `neo4jcsv`, `dot` |

Из `JoernExport.scala`: в `exportWithFlatgraphFormat` ветки есть ровно для `All` и `Cpg`, для прочих — `throw new NotImplementedError(...)`. То есть **комбинация `--repr=pdg --format=graphml` не работает**.

**Принятое решение:** основной путь — **CPGQL-скрипты** с выводом в JSON. Это даёт точный контроль над тем, что именно мы извлекаем (нам нужны вызовы и методы, а не весь граф), и не требует парсинга GraphML/DOT. Скрипты находятся в `src/ragraf/cpg.py` (`QUERY_CALLS`, `QUERY_METHODS`, `QUERY_TYPES`).

Дополнительно: `joern-export` **сам** достраивает оверлеи данных (`addDataFlowOverlayIfNonExistent` вызывает `OssDataFlow`), поэтому отдельный прогон оверлея для PDG не нужен.

---

## 4. Ограничения php2cpg, критичные для нашего корпуса

### 4.1. Синтаксис ограничен PHP 8.2

Бандленный парсер — `nikic/PHP-Parser` ветки 4.x:

- `MODULE.bazel`: `PHP_PARSER_VERSION = "4.15.10"`;
- README форка: *«This is a PHP 5.2 to PHP 8.2 parser written in PHP»*.

Пилот — **PHP 8.4**. Новые конструкции (property hooks, асимметричная видимость) в грамматике 4.x отсутствуют → синтаксические ошибки.

**Смягчающий фактор:** фронтенд всегда передаёт `--with-recovery`, поэтому ожидается неполный AST, а не падение. Насколько неполный — проверяется на прогоне.

**Что делать:** считать это в метрике полноты. В отчёте появится отдельная строка о файлах, которые php2cpg не разобрал (в логах это `Failed to process '<файл>'` — предупреждение, при котором файл молча выпадает; такое надо ловить).

### 4.2. Нет composer.json → неполное разрешение имён

`buildFiles` ищет **только** `composer.json`: `SourceFiles.determine(config.inputPath, Set(".json"), …).filter(_.endsWith("composer.json"))`. У пилота composer.json нет (PHP без фреймворка, автозагрузка через `spl_autoload_register`).

**Смягчающий фактор:** фронтенд проходит код **дважды** — `SymbolSummaryPass` собирает символы по всем пространствам имён, затем `AstCreationPass` строит AST с этой сводкой (*«parses the code twice… This helps resolve symbols during the latter parse»*). Связи внутри проекта частично разрешатся.

### 4.3. JDK 21 вне протестированного диапазона

docs.joern.io/installation: *«JDK 19 … newer JDK versions might work, but have not been properly tested»*. У нас JDK 21.

Отдельное предупреждение в документации срезов: *«Class path issues related to Circe are known to rear its head on Java versions later than 17»* — касается именно `joern-slice`.

**Что делать:** если `joern-slice` упадёт на JDK 21, альтернатива — срезы нашими средствами через CPGQL (обход CFG/DDG), либо установка JDK 19. Это выяснится на первом прогоне.

### 4.4. Инкрементального обновления CPG нет

Ни `joern-parse`, ни `joern-export`, ни документация не описывают инкрементальную пересборку; `joern-scan --overwrite` описан как полная регенерация.

**Следствие:** CPG пересобирается целиком при каждой переиндексации. Это согласуется с принципами проекта (индекс иммутабелен в пределах ревизии, переиндексация — отдельный акт), но означает, что стадия CPG — самая дорогая в прогоне, и её время надо измерять.

---

## 5. Связь CPG с нашим графом

| Узел CPG | Ключевые свойства | Ключ склейки с нашими узлами |
|---|---|---|
| `FILE` | `name` | путь исходника |
| `METHOD` | `name`, `fullName`, `filename`, `lineNumber`, `lineNumberEnd`, `isExternal` | `(filename, lineNumber, name)` |
| `TYPE_DECL` | `name`, `fullName`, `filename`, `lineNumber` | классы, интерфейсы, traits, enum |
| `CALL` | `name`, `code`, `methodFullName`, `dispatchType`, `lineNumber`, `columnNumber` | **`methodFullName` — то, чего нет в tree-sitter индексе** |
| `IDENTIFIER`, `LITERAL`, `LOCAL`, `PARAMETER` | `name`, `code`, `lineNumber`, `typeFullName` | переменные и значения |

`dispatchType` различает `STATIC_DISPATCH` и `DYNAMIC_DISPATCH` — это готовый признак для разделения доказанных и эвристических связей.

**Реализованное разрешение имён** (`Indexer._make_fqn_resolver`): точное совпадение полного имени → совпадение имени метода и файла → **отказ**. Третий исход принципиален: в PHP без фреймворка короткие имена (`get`, `run`) есть у десятков классов, и привязка «по имени» дала бы ровно те выдуманные связи, от которых защищает принцип P3 архитектуры.

**Не проверено:** база нумерации строк у php-parser (1-based или 0-based). Проверяется сверкой на первом прогоне; при расхождении на 1 нужна поправка в ключе склейки.

---

## 6. Что осталось выяснить запуском

| Вопрос | Как проверяется |
|---|---|
| Наличие и точные имена исполняемых файлов в дистрибутиве | `scripts/install-joern.ps1` (делает это автоматически) |
| Работает ли `joern-parse --language PHP` на нашем корпусе | первый прогон стадии CPG |
| Сколько файлов php2cpg не разберёт из-за PHP 8.4 | сверка с логом Joern и с результатом tree-sitter (у нас 0 ошибок разбора) |
| Время сборки CPG на 112 тыс. строк PHP | замер стадии `cpg` |
| Потребление памяти и нужный `-Xmx` | замер + наблюдение |
| Совпадает ли `lineNumber` CPG с нашими строками | сверка 20 методов вручную |
| Работает ли `joern-slice` на JDK 21 | отдельный прогон |

---

## 7. Состояние на момент написания

| Компонент | Состояние |
|---|---|
| JDK 21 (Temurin 21.0.12.1) | ✅ установлен в `.tools/jdk`, проверен запуском |
| PHP CLI 8.5 | ✅ найден (`C:\tools\php85\php.exe`) — предусловие php2cpg выполнено |
| Joern 4.0.99 | ✅ установлен в `.tools/joern-cli` (1633 МБ), `php` подтверждён в `--list-languages` |
| Слой CPG в конвейере (`src/ragraf/cpg.py`) | ✅ работает: `capability=full` на пилоте |
| Разбор экспорта (`src/ragraf/joern_export.py`) | ✅ neo4jcsv через ijson |
| Стадия `cpg` в индексаторе | ✅ слияние подтверждённых вызовов с нашим графом |
| Скрипт установки | ✅ `scripts/install-joern.ps1` |

---

## 8. Что выяснилось только запуском (факты, которых нет в документации)

Это самая ценная часть: документация Joern не описывает ни одного из этих пунктов, а без них слой CPG не работает.

| № | Обнаружено | Как проявлялось | Решение |
|---|---|---|---|
| 1 | `php2cpg` **требует внешний `php` в PATH** (в нём нет собственного парсера) | без PHP фронтенд не стартует вообще | `find_php()` + подстановка каталога с php первым в PATH |
| 2 | **php2cpg не принимает `--exclude`** | `Unknown option --exclude` → `RuntimeException: unable to parse XTypeStubsParserConfig` | отсев служебных путей ПОСЛЕ экспорта (`is_noise_file`) |
| 3 | **Скриптовый режим (`--script`) на JDK 21 не работает** | ошибка компиляции: нет predef-скрипта (`importCpg`, `cpg` не найдены) | полностью перешли на `joern-export` |
| 4 | **Экспорт GraphSON падает по памяти даже на 18 ГБ** | `OutOfMemoryError: Required array length 2147483640 + 8 is too large` | формат `neo4jcsv`: потоковые CSV, 223 МБ, 27 с |
| 5 | **`--repr=cpg` создаёт файл на каждый метод и падает** | 731 файл, 739 МБ, `FileSystemException` | `--repr=all` + фильтрация при разборе |
| 6 | **`JAVA_OPTS` не доходит до JVM** | `OutOfMemoryError` при любом значении переменной | лимит передаётся аргументом `-J-Xmx18g` (форма без `=`) |
| 7 | **Пути Joern не совпадают с нашими** | ведущая точка и обратные слеши; сопоставление всегда давало отказ | `normalize_joern_path` |
| 8 | **Методы Joern пишутся через `->`, а не `::`** | `App\Core\Config->get` не сопоставлялось ни с чем | `normalize_joern_name`; результат: 411 связей по полному имени |
| 9 | **AST-обход без границы метода захватывает всё** | заглушка `<global>` есть в каждом файле и содержит весь файл: 179 330 из 183 357 вызовов получили её владельцем | остановка обхода на вложенных METHOD |
| 10 | **В экспорте Joern массив вершин называется `vertices`, а не `nodes`** | разбор давал 0 узлов при 83 542 разобранных рёбрах | ключ `@value.vertices.item`; свойства — в `properties` под именами в ВЕРХНЕМ РЕГИСТРЕ |
| 11 | **Большинство CALL — операторы языка** | 50 тыс. из 183 тыс. — `<operator>.assignment` | `_is_noise_call`; осталось 17 822 настоящих вызова |
| 12 | **Встроенные функции PHP надо классифицировать отдельно** | 13 008 из 17 822 «не разрешено» были `array_push`, `is_array`, `Iterator.next` | `_is_builtin_target`: 7 819 распознаны как норма, честный остаток — 4 985 |

**Урок для проекта.** Из 12 пунктов 7 приводили к **молчаливой** потере данных: код не падал, но результат оказывался нулевым или искажённым. Такие дефекты ловятся только сверкой независимых путей — ровно как было с CPGQL (работал в теории, не работал на практике) и с фильтром `<global>` (формально обход корректен, фактически почти все данные у одного владельца).

---

## 9. Результат на пилоте

| Показатель | Значение |
|---|---|
| `capability` | **full** (CPG подключена) |
| Время полной индексации с CPG | 71 с (из них CPG — 64 с) |
| Сборка CPG | 18.6 МБ, ~50 с на 323 файла |
| Экспорт | 223.8 МБ, 132 файла, ~27 с |
| Значимых вершин извлечено | 193 442 |
| Рёбер извлечено | 3 348 516 (в т.ч. 444 464 CFG, 930 567 потоков данных) |
| Вызовов после фильтрации | 17 822 из 183 357 |
| **Связей подтверждено в графе** | **603** (411 по полному имени, 192 по имени и файлу) |
| Встроенных функций PHP распознано | 7 819 |
| Честно не разрешено | 4 985 |
| `slice` | **работает** (был недоступен в режиме degraded) |
| **Влияние на M2** | **recall 0,771 → 0,858**; медиана 1,000; нулевых случаев 0 (было 1); полная связность у 13 из 20 (было 11) |