ora2pg-gap-report 0.1.0__tar.gz

ora2pg_gap_report-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ora2pg-gap-report contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ora2pg_gap_report-0.1.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: ora2pg-gap-report
+Version: 0.1.0
+Summary: Сканер Oracle-схемы, дополняющий ora2pg: находит объекты, которые он не перенесёт или перенесёт некорректно, до начала миграции на Postgres Pro.
+Author: Lunch418
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Lunch418/ora2pg-gap-report
+Keywords: oracle,postgresql,ora2pg,migration,plsql
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Database
+Classifier: Environment :: Console
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13
+Provides-Extra: oracle
+Requires-Dist: oracledb>=2.0; extra == "oracle"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# ora2pg-gap-report
+
+[![tests](https://github.com/Lunch418/ora2pg-gap-report/actions/workflows/tests.yml/badge.svg)](https://github.com/Lunch418/ora2pg-gap-report/actions/workflows/tests.yml)
+
+Инструмент для оценки миграции Oracle → PostgreSQL Pro (Standard/Certified) **до** её начала.
+
+## Проблема
+
+При миграции с Oracle на Postgres Pro в сегменте Standard/Certified (то есть без
+лицензии на Postgres Pro Enterprise и без проприетарной утилиты `ora2pgpro`)
+единственный доступный автоматический конвертер — открытый
+[`ora2pg`](https://github.com/darold/ora2pg). По независимым оценкам он закрывает
+в среднем ~80% задачи перевода PL/SQL → PL/pgSQL. Оставшиеся ~20% (пакеты,
+автономные транзакции, `CONNECT BY`, вызовы `DBMS_*`/`UTL_*`, составные триггеры)
+сейчас разбираются вручную и, как правило, обнаруживаются постфактум — когда
+что-то уже сломалось в проде.
+
+## Что делает этот инструмент
+
+Сканирует схему Oracle **до** миграции и говорит: какие конкретно объекты
+`ora2pg` пропустит без предупреждения, недооценит по трудоёмкости или
+сконвертирует потенциально некорректно — и почему. Не замена `ora2pg`, а
+надстройка над ним: список того, что он реально не переносит, проверен
+эмпирически на открытом PL/SQL-коде (`docs/research/step0-show-report-baseline.md`),
+а не взят на веру.
+
+## Детекторы
+
+| Детектор | Что ловит |
+|---|---|
+| `autonomous_tx` | `PRAGMA AUTONOMOUS_TRANSACTION` внутри `PACKAGE BODY` — ora2pg конвертирует через dblink, но занижает/теряет стоимость в `SHOW_REPORT`/`--estimate_cost` |
+| `compound_triggers` | `COMPOUND TRIGGER` — файловый парсер ora2pg тихо возвращает 0 триггеров, без единой ошибки |
+| `dbms_utl_calls` | Классификатор конкретных вызовов `DBMS_*`/`UTL_*` — что из них ora2pg реально конвертирует, а что остаётся как есть |
+| `connect_by` | Линтинг сгенерированного ora2pg `WITH RECURSIVE` на баг с `LEVEL`. Включается флагом `--check-connect-by` и, в отличие от остальных, требует установленный `ora2pg` |
+
+Плюс `ora2pg_wrapper.py` — запуск `ora2pg` по типам объектов на выгруженном
+DDL с парсингом `--estimate_cost`, и `oracle_connector.py`/`oracle_export.py`
+— живая выгрузка `PACKAGE BODY`/`TRIGGER` прямо из Oracle-схемы через
+`DBMS_METADATA.GET_DDL`.
+
+## Установка и использование
+
+```sh
+pip install ora2pg-gap-report   # (или: pip install . из клона репозитория)
+```
+
+Сама детекторная библиотека (`detectors/`, `models.py`,
+`report_generator.py`) — чистый Python без единой внешней зависимости, её
+можно импортировать отдельно (например, в своих скриптах) вообще без
+установки чего-либо ещё. У CLI есть одна обязательная зависимость —
+[`rich`](https://github.com/Textualize/rich), только ради приятного
+терминального вывода; ставится сама через `pip install`.
+
+Сразу после установки доступна команда:
+
+```sh
+ora2pg-gap-report path/to/schema_dump.pkb another_file.sql
+```
+
+В интерактивном терминале по умолчанию — цветной отчёт: сводная панель
+(сколько найдено, разбивка по severity, грубая оценка часов), компактная
+таблица находок и пояснения под каждым сработавшим детектором. Для
+скриптов/redirect — `--format markdown` или `--format json` (тоже
+работают как формат по умолчанию, если stdout не терминал):
+
+```sh
+ora2pg-gap-report path/to/schema_dump.pkb --format json --output report.json
+ora2pg-gap-report path/to/schema_dump.pkb --format markdown > report.md
+
+# Опционально: линтинг сгенерированного ora2pg кода для CONNECT BY.
+# Требует установленный ora2pg (см. https://github.com/darold/ora2pg) —
+# единственная внешняя (не-Python) зависимость во всём проекте, и только
+# для этой конкретной проверки.
+ora2pg-gap-report path/to/schema_dump.pkb --check-connect-by
+```
+
+Файлы с DDL можно передавать как есть — один файл может содержать сразу
+несколько пакетов/триггеров, детекторы разбирают границы объектов сами.
+
+Пример реального вывода на открытом пакете —
+[`docs/examples/logger-autonomous_tx-report.md`](docs/examples/logger-autonomous_tx-report.md).
+
+Оценка трудозатрат в отчёте — грубая эвристика по severity (диапазон
+часов, не точечное число). Это ориентир для планирования, а не
+откалиброванная на реальных миграциях оценка — не стоит выдавать её
+клиенту как обязательство.
+
+## Выгрузка DDL прямо из Oracle (опционально)
+
+Если под рукой живая Oracle-схема, а не уже готовый DDL-дамп:
+
+```sh
+pip install "ora2pg-gap-report[oracle]"   # добавляет python-oracledb, thin-режим, без Instant Client
+
+ora2pg-gap-export --dsn host:1521/ORCLPDB1 --user hr --output-dir dumps/
+# пароль — из переменной окружения ORACLE_PASSWORD, либо будет запрошен интерактивно
+
+ora2pg-gap-report dumps/*.sql
+```
+
+`ora2pg-gap-export` — отдельная команда, не флаг у `ora2pg-gap-report`,
+специально: выгрузка требует сетевого доступа к Oracle, анализ — никогда.
+В закрытом контуре это часто две разные машины (jump host с доступом к БД
+и изолированная рабочая станция для анализа) — единственное, что должно
+пересечь границу между ними, это уже выгруженные `.sql` файлы.
+
+## Установка без интернета (закрытый контур)
+
+Целевая аудитория этого инструмента — как раз изолированные сети без
+выхода наружу, поэтому `pip install` там обычно не вариант. Решение —
+собрать самодостаточный архив на машине с интернетом, перенести его
+любым доступным способом (`scp`/`sftp`/через jump host/на флешке) и
+поставить на целевой машине уже совсем без сети:
+
+```sh
+# На машине с интернетом, из клона репозитория:
+python scripts/build_offline_bundle.py --oracle   # --oracle опционально, --dev для pytest
+# → ora2pg-gap-report-offline.tar.gz (пакет + rich + всё транзитивно,
+#   включая oracledb и его зависимости, если указан --oracle)
+
+scp ora2pg-gap-report-offline.tar.gz user@jump-host:/tmp/
+# ...дальше как получится добраться до целевой машины в контуре —
+# sftp, ещё один jump host, физический перенос
+
+# На целевой машине БЕЗ интернета:
+tar xzf ora2pg-gap-report-offline.tar.gz
+cd ora2pg-gap-report-offline
+./install.sh oracle        # или: python3 install.py oracle
+```
+
+`install.sh`/`install.py` вызывают `pip install --no-index --find-links=./wheels
+...` — pip ставит целиком из положенных рядом `.whl`-файлов, ни одного
+обращения в сеть.
+
+`rich` и его зависимости (`markdown-it-py`, `pygments`, `mdurl`) —
+чистый Python, один набор wheel-файлов работает везде. `oracledb`
+(только при `--oracle`) собирает платформозависимые wheel — если
+машина сборки отличается от целевой по ОС/архитектуре/версии Python,
+передайте `--platform`/`--python-version`/`--abi` в
+`build_offline_bundle.py` (см. `--help`), чтобы скачать wheel именно
+под целевую платформу, а не под ту, где запущен скрипт.
+
+## Архитектура
+
+`ora2pg SHOW_REPORT` целиком не имеет офлайн-режима — он требует живого
+подключения к Oracle (`ORACLE_DSN`). Офлайн от DDL-дампа работает только
+анализ *отдельных типов объектов* (`-t PACKAGE`, `-t TRIGGER`, `-t FUNCTION`,
+…) — именно так работает `ora2pg_wrapper.py`, а не через `SHOW_REPORT`. Это
+принципиально для целевой аудитории — закрытые контуры, air-gapped среды,
+госсектор.
+
+Три из четырёх детекторов (`autonomous_tx`, `compound_triggers`,
+`dbms_utl_calls`) анализируют Oracle-исходник напрямую и не требуют
+установленного `ora2pg` — чистый Python, без внешних зависимостей.
+Четвёртый (`connect_by`) устроен иначе: он линтит *сгенерированный*
+ora2pg-код, а не исходник (ora2pg сам неплохо считает CONNECT BY —
+ценность не в обнаружении, а в проверке качества конвертации), поэтому
+ему нужен реальный `ora2pg` и он подключается только через
+`--check-connect-by`.
+
+```
+pyproject.toml                 # единственный источник правды по зависимостям/точкам входа
+ora2pg_gap_report/
+├── models.py                  # Finding — общая структура находки для всех детекторов
+├── plsql_lex.py                # общая инфраструктура: маскирование строк/комментариев
+│                               # (включая q-quote), сопоставление блоков BEGIN/CASE/IF/LOOP...END,
+│                               # разбор идентификаторов — используется всеми детекторами
+├── oracle_connector.py         # живая выгрузка PACKAGE BODY/TRIGGER через DBMS_METADATA.GET_DDL
+├── oracle_export.py            # консольная команда ora2pg-gap-export
+├── detectors/
+│   ├── autonomous_tx.py        # PRAGMA AUTONOMOUS_TRANSACTION в PACKAGE BODY
+│   ├── compound_triggers.py    # COMPOUND TRIGGER — тихий провал парсинга у ora2pg
+│   ├── dbms_utl_calls.py       # классификатор конкретных DBMS_*/UTL_* функций
+│   └── connect_by.py           # линтинг сгенерированного WITH RECURSIVE (нужен ora2pg)
+├── ora2pg_wrapper.py            # запуск ora2pg по типам объектов, парсинг --estimate_cost
+├── cli.py                      # консольная команда ora2pg-gap-report
+├── effort_estimator.py          # грубая эвристика по severity, диапазон часов
+├── report_generator.py          # JSON + Markdown (машиночитаемые форматы)
+└── terminal_report.py           # цветной вывод через rich (единственная зависимость;
+                                 #  библиотеки-детекторов не касается, только CLI)
+tests/
+├── fixtures/                   # реальные захваченные прогоны ora2pg — тесты парсера не требуют
+│                               # установленного ora2pg, кроме нескольких live-тестов
+│                               # (пропускаются автоматически, если ora2pg не найден в PATH)
+docs/research/                  # эмпирическая проверка предпосылок, реальные PL/SQL примеры
+docs/examples/                  # примеры вывода детекторов на реальных данных
+scripts/
+├── build_offline_bundle.py     # сборка автономного архива для установки без интернета
+├── oracle-test-compose.yml     # Oracle Free 23ai в Docker для живой проверки
+├── setup_oracle_test_schema.sql
+└── verify_against_live_oracle.py
+.github/workflows/tests.yml     # CI: pytest на 3.10-3.13 + сборка и smoke-test пакета
+```
+
+## Тестирование
+
+```sh
+pip install -e ".[dev]"   # editable-режим + pytest
+pytest
+```
+
+Детекторы и лексер проверены на реальном открытом PL/SQL-коде (Logger,
+alexandria-plsql-utils, составной триггер из Apress), а не только на
+синтетических примерах.
+
+### Проверка на живой Oracle
+
+Юнит-тесты `oracle_connector.py` идут на fake-соединении
+(`tests/fakes/fake_oracle.py`) — быстро, детерминированно, не требует
+Oracle. Живой путь ("подключился к настоящей Oracle → выгрузил через
+`DBMS_METADATA.GET_DDL` → проанализировал") ими не покрыт — для него
+нужна настоящая база:
+
+```sh
+docker compose -f scripts/oracle-test-compose.yml up -d
+docker compose -f scripts/oracle-test-compose.yml logs -f   # ждать "DATABASE IS READY TO USE"
+
+pip install -e ".[oracle]"
+ORACLE_DSN=localhost:1521/FREEPDB1 ORACLE_USER=testuser ORACLE_PASSWORD=testpass1 \
+  python scripts/verify_against_live_oracle.py
+```
+
+Скрипт создаёт пару служебных таблиц (`scripts/setup_oracle_test_schema.sql`
+— триггерам, в отличие от пакетов, нужна реально существующая целевая
+таблица), заливает реальные фикстуры из `docs/research/samples/` как
+есть, выгружает их обратно живым `DBMS_METADATA.GET_DDL`, прогоняет
+детекторы и сверяет счётчики с уже независимо проверенными на этих же
+файлах как на тексте (`tests/`). Если в `PATH` есть `ora2pg` — заодно
+прогоняет `SHOW_REPORT` против живого подключения.
+
+`gvenzl/oracle-free:23-slim` — контейнерный пакет официального
+бесплатного дистрибутива Oracle (тот же движок), просто с более удобной
+для CI/тестов оберткой, чем прямой образ Oracle Container Registry.
+
+## Лицензия
+
+MIT, см. [LICENSE](LICENSE).

ora2pg_gap_report-0.1.0/README.md

@@ -0,0 +1,237 @@
+# ora2pg-gap-report
+
+[![tests](https://github.com/Lunch418/ora2pg-gap-report/actions/workflows/tests.yml/badge.svg)](https://github.com/Lunch418/ora2pg-gap-report/actions/workflows/tests.yml)
+
+Инструмент для оценки миграции Oracle → PostgreSQL Pro (Standard/Certified) **до** её начала.
+
+## Проблема
+
+При миграции с Oracle на Postgres Pro в сегменте Standard/Certified (то есть без
+лицензии на Postgres Pro Enterprise и без проприетарной утилиты `ora2pgpro`)
+единственный доступный автоматический конвертер — открытый
+[`ora2pg`](https://github.com/darold/ora2pg). По независимым оценкам он закрывает
+в среднем ~80% задачи перевода PL/SQL → PL/pgSQL. Оставшиеся ~20% (пакеты,
+автономные транзакции, `CONNECT BY`, вызовы `DBMS_*`/`UTL_*`, составные триггеры)
+сейчас разбираются вручную и, как правило, обнаруживаются постфактум — когда
+что-то уже сломалось в проде.
+
+## Что делает этот инструмент
+
+Сканирует схему Oracle **до** миграции и говорит: какие конкретно объекты
+`ora2pg` пропустит без предупреждения, недооценит по трудоёмкости или
+сконвертирует потенциально некорректно — и почему. Не замена `ora2pg`, а
+надстройка над ним: список того, что он реально не переносит, проверен
+эмпирически на открытом PL/SQL-коде (`docs/research/step0-show-report-baseline.md`),
+а не взят на веру.
+
+## Детекторы
+
+| Детектор | Что ловит |
+|---|---|
+| `autonomous_tx` | `PRAGMA AUTONOMOUS_TRANSACTION` внутри `PACKAGE BODY` — ora2pg конвертирует через dblink, но занижает/теряет стоимость в `SHOW_REPORT`/`--estimate_cost` |
+| `compound_triggers` | `COMPOUND TRIGGER` — файловый парсер ora2pg тихо возвращает 0 триггеров, без единой ошибки |
+| `dbms_utl_calls` | Классификатор конкретных вызовов `DBMS_*`/`UTL_*` — что из них ora2pg реально конвертирует, а что остаётся как есть |
+| `connect_by` | Линтинг сгенерированного ora2pg `WITH RECURSIVE` на баг с `LEVEL`. Включается флагом `--check-connect-by` и, в отличие от остальных, требует установленный `ora2pg` |
+
+Плюс `ora2pg_wrapper.py` — запуск `ora2pg` по типам объектов на выгруженном
+DDL с парсингом `--estimate_cost`, и `oracle_connector.py`/`oracle_export.py`
+— живая выгрузка `PACKAGE BODY`/`TRIGGER` прямо из Oracle-схемы через
+`DBMS_METADATA.GET_DDL`.
+
+## Установка и использование
+
+```sh
+pip install ora2pg-gap-report   # (или: pip install . из клона репозитория)
+```
+
+Сама детекторная библиотека (`detectors/`, `models.py`,
+`report_generator.py`) — чистый Python без единой внешней зависимости, её
+можно импортировать отдельно (например, в своих скриптах) вообще без
+установки чего-либо ещё. У CLI есть одна обязательная зависимость —
+[`rich`](https://github.com/Textualize/rich), только ради приятного
+терминального вывода; ставится сама через `pip install`.
+
+Сразу после установки доступна команда:
+
+```sh
+ora2pg-gap-report path/to/schema_dump.pkb another_file.sql
+```
+
+В интерактивном терминале по умолчанию — цветной отчёт: сводная панель
+(сколько найдено, разбивка по severity, грубая оценка часов), компактная
+таблица находок и пояснения под каждым сработавшим детектором. Для
+скриптов/redirect — `--format markdown` или `--format json` (тоже
+работают как формат по умолчанию, если stdout не терминал):
+
+```sh
+ora2pg-gap-report path/to/schema_dump.pkb --format json --output report.json
+ora2pg-gap-report path/to/schema_dump.pkb --format markdown > report.md
+
+# Опционально: линтинг сгенерированного ora2pg кода для CONNECT BY.
+# Требует установленный ora2pg (см. https://github.com/darold/ora2pg) —
+# единственная внешняя (не-Python) зависимость во всём проекте, и только
+# для этой конкретной проверки.
+ora2pg-gap-report path/to/schema_dump.pkb --check-connect-by
+```
+
+Файлы с DDL можно передавать как есть — один файл может содержать сразу
+несколько пакетов/триггеров, детекторы разбирают границы объектов сами.
+
+Пример реального вывода на открытом пакете —
+[`docs/examples/logger-autonomous_tx-report.md`](docs/examples/logger-autonomous_tx-report.md).
+
+Оценка трудозатрат в отчёте — грубая эвристика по severity (диапазон
+часов, не точечное число). Это ориентир для планирования, а не
+откалиброванная на реальных миграциях оценка — не стоит выдавать её
+клиенту как обязательство.
+
+## Выгрузка DDL прямо из Oracle (опционально)
+
+Если под рукой живая Oracle-схема, а не уже готовый DDL-дамп:
+
+```sh
+pip install "ora2pg-gap-report[oracle]"   # добавляет python-oracledb, thin-режим, без Instant Client
+
+ora2pg-gap-export --dsn host:1521/ORCLPDB1 --user hr --output-dir dumps/
+# пароль — из переменной окружения ORACLE_PASSWORD, либо будет запрошен интерактивно
+
+ora2pg-gap-report dumps/*.sql
+```
+
+`ora2pg-gap-export` — отдельная команда, не флаг у `ora2pg-gap-report`,
+специально: выгрузка требует сетевого доступа к Oracle, анализ — никогда.
+В закрытом контуре это часто две разные машины (jump host с доступом к БД
+и изолированная рабочая станция для анализа) — единственное, что должно
+пересечь границу между ними, это уже выгруженные `.sql` файлы.
+
+## Установка без интернета (закрытый контур)
+
+Целевая аудитория этого инструмента — как раз изолированные сети без
+выхода наружу, поэтому `pip install` там обычно не вариант. Решение —
+собрать самодостаточный архив на машине с интернетом, перенести его
+любым доступным способом (`scp`/`sftp`/через jump host/на флешке) и
+поставить на целевой машине уже совсем без сети:
+
+```sh
+# На машине с интернетом, из клона репозитория:
+python scripts/build_offline_bundle.py --oracle   # --oracle опционально, --dev для pytest
+# → ora2pg-gap-report-offline.tar.gz (пакет + rich + всё транзитивно,
+#   включая oracledb и его зависимости, если указан --oracle)
+
+scp ora2pg-gap-report-offline.tar.gz user@jump-host:/tmp/
+# ...дальше как получится добраться до целевой машины в контуре —
+# sftp, ещё один jump host, физический перенос
+
+# На целевой машине БЕЗ интернета:
+tar xzf ora2pg-gap-report-offline.tar.gz
+cd ora2pg-gap-report-offline
+./install.sh oracle        # или: python3 install.py oracle
+```
+
+`install.sh`/`install.py` вызывают `pip install --no-index --find-links=./wheels
+...` — pip ставит целиком из положенных рядом `.whl`-файлов, ни одного
+обращения в сеть.
+
+`rich` и его зависимости (`markdown-it-py`, `pygments`, `mdurl`) —
+чистый Python, один набор wheel-файлов работает везде. `oracledb`
+(только при `--oracle`) собирает платформозависимые wheel — если
+машина сборки отличается от целевой по ОС/архитектуре/версии Python,
+передайте `--platform`/`--python-version`/`--abi` в
+`build_offline_bundle.py` (см. `--help`), чтобы скачать wheel именно
+под целевую платформу, а не под ту, где запущен скрипт.
+
+## Архитектура
+
+`ora2pg SHOW_REPORT` целиком не имеет офлайн-режима — он требует живого
+подключения к Oracle (`ORACLE_DSN`). Офлайн от DDL-дампа работает только
+анализ *отдельных типов объектов* (`-t PACKAGE`, `-t TRIGGER`, `-t FUNCTION`,
+…) — именно так работает `ora2pg_wrapper.py`, а не через `SHOW_REPORT`. Это
+принципиально для целевой аудитории — закрытые контуры, air-gapped среды,
+госсектор.
+
+Три из четырёх детекторов (`autonomous_tx`, `compound_triggers`,
+`dbms_utl_calls`) анализируют Oracle-исходник напрямую и не требуют
+установленного `ora2pg` — чистый Python, без внешних зависимостей.
+Четвёртый (`connect_by`) устроен иначе: он линтит *сгенерированный*
+ora2pg-код, а не исходник (ora2pg сам неплохо считает CONNECT BY —
+ценность не в обнаружении, а в проверке качества конвертации), поэтому
+ему нужен реальный `ora2pg` и он подключается только через
+`--check-connect-by`.
+
+```
+pyproject.toml                 # единственный источник правды по зависимостям/точкам входа
+ora2pg_gap_report/
+├── models.py                  # Finding — общая структура находки для всех детекторов
+├── plsql_lex.py                # общая инфраструктура: маскирование строк/комментариев
+│                               # (включая q-quote), сопоставление блоков BEGIN/CASE/IF/LOOP...END,
+│                               # разбор идентификаторов — используется всеми детекторами
+├── oracle_connector.py         # живая выгрузка PACKAGE BODY/TRIGGER через DBMS_METADATA.GET_DDL
+├── oracle_export.py            # консольная команда ora2pg-gap-export
+├── detectors/
+│   ├── autonomous_tx.py        # PRAGMA AUTONOMOUS_TRANSACTION в PACKAGE BODY
+│   ├── compound_triggers.py    # COMPOUND TRIGGER — тихий провал парсинга у ora2pg
+│   ├── dbms_utl_calls.py       # классификатор конкретных DBMS_*/UTL_* функций
+│   └── connect_by.py           # линтинг сгенерированного WITH RECURSIVE (нужен ora2pg)
+├── ora2pg_wrapper.py            # запуск ora2pg по типам объектов, парсинг --estimate_cost
+├── cli.py                      # консольная команда ora2pg-gap-report
+├── effort_estimator.py          # грубая эвристика по severity, диапазон часов
+├── report_generator.py          # JSON + Markdown (машиночитаемые форматы)
+└── terminal_report.py           # цветной вывод через rich (единственная зависимость;
+                                 #  библиотеки-детекторов не касается, только CLI)
+tests/
+├── fixtures/                   # реальные захваченные прогоны ora2pg — тесты парсера не требуют
+│                               # установленного ora2pg, кроме нескольких live-тестов
+│                               # (пропускаются автоматически, если ora2pg не найден в PATH)
+docs/research/                  # эмпирическая проверка предпосылок, реальные PL/SQL примеры
+docs/examples/                  # примеры вывода детекторов на реальных данных
+scripts/
+├── build_offline_bundle.py     # сборка автономного архива для установки без интернета
+├── oracle-test-compose.yml     # Oracle Free 23ai в Docker для живой проверки
+├── setup_oracle_test_schema.sql
+└── verify_against_live_oracle.py
+.github/workflows/tests.yml     # CI: pytest на 3.10-3.13 + сборка и smoke-test пакета
+```
+
+## Тестирование
+
+```sh
+pip install -e ".[dev]"   # editable-режим + pytest
+pytest
+```
+
+Детекторы и лексер проверены на реальном открытом PL/SQL-коде (Logger,
+alexandria-plsql-utils, составной триггер из Apress), а не только на
+синтетических примерах.
+
+### Проверка на живой Oracle
+
+Юнит-тесты `oracle_connector.py` идут на fake-соединении
+(`tests/fakes/fake_oracle.py`) — быстро, детерминированно, не требует
+Oracle. Живой путь ("подключился к настоящей Oracle → выгрузил через
+`DBMS_METADATA.GET_DDL` → проанализировал") ими не покрыт — для него
+нужна настоящая база:
+
+```sh
+docker compose -f scripts/oracle-test-compose.yml up -d
+docker compose -f scripts/oracle-test-compose.yml logs -f   # ждать "DATABASE IS READY TO USE"
+
+pip install -e ".[oracle]"
+ORACLE_DSN=localhost:1521/FREEPDB1 ORACLE_USER=testuser ORACLE_PASSWORD=testpass1 \
+  python scripts/verify_against_live_oracle.py
+```
+
+Скрипт создаёт пару служебных таблиц (`scripts/setup_oracle_test_schema.sql`
+— триггерам, в отличие от пакетов, нужна реально существующая целевая
+таблица), заливает реальные фикстуры из `docs/research/samples/` как
+есть, выгружает их обратно живым `DBMS_METADATA.GET_DDL`, прогоняет
+детекторы и сверяет счётчики с уже независимо проверенными на этих же
+файлах как на тексте (`tests/`). Если в `PATH` есть `ora2pg` — заодно
+прогоняет `SHOW_REPORT` против живого подключения.
+
+`gvenzl/oracle-free:23-slim` — контейнерный пакет официального
+бесплатного дистрибутива Oracle (тот же движок), просто с более удобной
+для CI/тестов оберткой, чем прямой образ Oracle Container Registry.
+
+## Лицензия
+
+MIT, см. [LICENSE](LICENSE).