# Супровід і діагностика

[Документація](README.md) · [English](../en/maintenance.md)

## Збереження потрібних звітів

Візьміть `outputRoot` із деталей результату інструмента або шлях `APEXlang reports:` із помилки виконання. Розширення передає цей каталог дочірнім процесам як `APEXLANG_OUTPUT_ROOT`; власний тимчасовий корінь створюється всередині розширення, а не задається параметром інструмента.

| Відносний шлях | Вміст |
| --- | --- |
| `logs/sqlcl-validate.json`, `logs/sqlcl-validate.log` | Результат і журнал версійованої компіляторної перевірки; не докази live/import |
| `sqlcl-apps/` | Повні тимчасові копії для компіляторної перевірки |
| `logs/apexlang-vocab-report.json` | Діагностики словника та непідтримуваної MMD |
| `logs/apexlang-dsl-report.json` | Діагностики перевірки DSL |
| `logs/apexlang-validations-report.json` | Діагностики правил валідацій |
| `logs/validation/` | Артефакти серверної перевірки, якщо їх створило середовище |
| `logs/runtime-run.json`, `logs/runtime-run.log` | Звіт і транскрипт roundtrip, якщо їх створено |
| `logs/compat/` | Докази сумісності, якщо використано відповідний шлях |
| `runtime-apps/` | Тимчасові копії застосунку |

Не кожна дія створює всі файли. Нові запуски очищають відомі застарілі докази, а завершення сесії видаляє весь корінь. Для довготривалого збереження скопіюйте потрібні звіти до каталогу доказів проєкту перед наступним запуском або завершенням сесії. Звіти можуть містити код, назви та діагностики застосунку; перегляньте їхній вміст перед передаванням іншим.

## Діагностика за симптомом

| Симптом | Наступний крок |
| --- | --- |
| `Missing Inputs` під час створення каркаса | Надайте достовірні метадані й підказку щодо ідентичності застосунку; повторіть probe та використайте точний `suggested_app_path`. |
| Відхилено шлях або символічне посилання | Відкрийте pi в корені потрібного проєкту й використайте справжній каталог застосунку всередині нього. |
| Виправлення словника відхиляє файл із кількома жорсткими посиланнями | Перед переписуванням зробіть потрібний файл застосунку незалежним. |
| Відхилено підключення чи workspace | Використайте збережений alias, а не рядок підключення; надайте відповідний workspace. |
| `deployments/default.json` відсутній або суперечливий | Перегляньте експортовані метадані розгортання та узгодьте потрібний workspace перед повтором. |
| Не вдається визначити властивості компілятора | Перевірте `mmdVersion` застосунку й доступні метадані компілятора; використайте `compiler_oracle_home` там, де його підтримано. |
| Багато діагностик у всьому застосунку | Перед масовими правками перевірте сумісність SQLcl/APEX/ORDS і метаданих компілятора. |
| Серверний процес успішно завершився, але імпорт недоступний | Перевірте поля доказів live-валідатора; самого коду завершення недостатньо. |
| Застосунок змінився після погодженої перевірки | Повторно перевірте поточний знімок застосунку. |
| Діалог після перевірки скасовано або сплив таймаут | Застосунок не імпортовано; замовте нову перевірку, якщо імпорт досі потрібний. |
| Таймаут процесу чи перевищення обсягу виводу | Перегляньте збережений вивід, діагностуйте через `runtime_doctor` і усуньте причину перед повтором. |

## Рекомендації щодо версій

[Машиночитана таблиця](../../extensions/apexlang/ords-sqlcl-compatibility.json) містить `policy=advisory-only` і дату перевірки **2026-10-21**. Збірка SQLcl **26.1.2.132.1334** у ній — діагностична базова версія для описаних сценаріїв APEX 26.1, а не універсально обов'язкова версія. SQLcl 26.2 не блокується категорично.

[Механізм рекомендацій](../../extensions/apexlang/compatibility.ts) спрацьовує за щонайменше **50 структурованих діагностик**. Для локальних JSON-звітів і текстового виводу compiler-truth додатково потрібні щонайменше **5 різних `.apx`-файлів**; дублікати діагностик прибираються. Явний `UNSUPPORTED_MMD_VERSION` у локальному звіті словника також викликає рекомендації.

Перевірте `sql -version`, `.apex/apexlang.json` → `mmdVersion`, а також версії APEX/ORDS на сервері разом із його адміністратором. Таблиця додає поради, не змінюючи статусу перевірки й не надаючи права імпорту. Зафіксовані мінімуми Oracle та діагностичні рекомендації проєкту мають різні значення `basis`; для інших гілок версій звертайтеся до пов'язаної документації випусків.

## Розробка та перевірки

З кореня репозиторію:

```bash
npm install --ignore-scripts
npm run check
```

`npm run check` послідовно виконує такі етапи:

| Етап | Що перевіряє |
| --- | --- |
| `typecheck` | Суворі перевірки TypeScript без створення вихідних файлів |
| `verify:vendor` | Хеш і походження зафіксованої копії Oracle |
| `test` | Контракти розширення/адаптера та відповідність результатів валідаторів |
| `smoke` | Probe порожнього тимчасового каталогу й локальну перевірку вбудованого каркаса |
| `verify:package` | Склад npm-пакета в dry-run і виключення файлів розробки/кешу |

Це локальні автоматизовані перевірки, а не доказ успішної серверної перевірки чи імпорту на реальному сервері. Workflow публікації запускається вручну й виконує `npm run check` перед публікацією; див. [publish-npm.yml](../../.github/workflows/publish-npm.yml).

## Оновлення копії Oracle

Підставте перевірений коміт/ref замість `<reviewed-ref>`:

```bash
npm run sync:oracle -- --ref <reviewed-ref>
npm run check
```

[Скрипт синхронізації](../../scripts/sync-oracle-apexlang.mjs) отримує репозиторій Oracle, замінює `skills/apexlang`, оновлює `LICENSE`, коміт/хеш у `UPSTREAM.json` і зафіксовані посилання в кореневому README та повідомленнях про сторонні компоненти. Під час заміни він використовує резервну копію. Перегляньте підсумковий diff перед комітом.

Власну поведінку реалізуйте в `extensions/`; локальні зміни в копії Oracle порушують перевірку її походження. Після зміни поведінки разом оновлюйте обидва мовні посібники й обидві інфографіки SVG/PNG. Дата/коміт посібників — знімок документації, який скрипт синхронізації Oracle не переписує автоматично.

## Матеріали документації

Інфографіки — редаговані SVG у [docs/assets](../assets) з PNG-копіями для поширення. Обидві мають однакові компонування та процес. SVG є джерелом кожного зображення; після зміни підписів або схеми оновіть PNG. Перелік npm `files` включає `docs`, щоб посилання на документацію з установленого README залишалися придатними.

Посилання на код/тести в цих посібниках стосуються Git checkout. `scripts/` і `test/` — ресурси розробки, які навмисно не входять до npm-пакета; для них відкрийте [репозиторій коду](https://github.com/avhrst/pi-apex). Ліцензія та атрибуція постачальника наведені в [LICENSE](../../LICENSE), [THIRD_PARTY_NOTICES.md](../../THIRD_PARTY_NOTICES.md) і [UPSTREAM.json](../../UPSTREAM.json).
