# Довідник інструмента

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

Зареєстрований інструмент має назву **`apexlang`**. Його API для моделі містить дев’ять наведених нижче дій. Схема визначена в [index.ts](../../extensions/apexlang/index.ts), а вимоги окремих дій і формування команд — в [apexlang-cli.mjs](../../extensions/lib/apexlang-cli.mjs).

Версію визначає `mmdVersion` у `.apex/apexlang.json` застосунку. Явний `apex_version` має збігатися; невідома версія означає 26.1, непідтримувана відхиляється. `sqlcl_validate` працює з 26.1 і 26.2. Решта операцій використовує generation runtime 26.1 (workspace probe лише шукає локальний контекст). Для розробки під 26.2 читайте його власні інвентар і приклади; upstream deploy skill включено, але серверний імпорт через GUI Pi доступний лише для 26.1.

## Дії

| Дія | Обов'язкові дані, крім `action` | Результат |
| --- | --- | --- |
| `workspace_probe` | Немає; якщо вказано підключення чи workspace, потрібні обидва | Шукає локальний контекст і можливі застосунки в установлених межах. |
| `new_app_materialize` | `app_path`, `db_connection_name`, `workspace_name`; достовірний результат probe | Створює базовий каркас після інтерактивного підтвердження лише за точним запропонованим шляхом. |
| `sqlcl_validate` | `app_path`; абсолютний `sqlcl_bin` або `SQLCL_BIN` | Виконує відповідний compile helper Oracle на тимчасовій копії через SQLcl `/nolog`. Без підключення до БД і без пропозиції імпорту. Потребує Bash. |
| `local_validate` | `apex_version` | `26.1` або `26.2`, необов’язково | Вибір версії; має збігатися з MMD застосунку |
| `sqlcl_bin` | Абсолютний шлях виконуваного SQLcl або змінна `SQLCL_BIN` | `sqlcl_validate` |
| `app_path` | Перевіряє словник, DSL і правила валідацій. `fix_vocab=true` переписує словник після підтвердження. |
| `compiler_truth_audit` | `app_path` | Виконує аудит за метаданими компілятора з обов'язково ввімкненою перевіркою атрибутів компонентів. |
| `query_valid_props` | Щонайменше одне з `component`, `component_type_id`, `template_component` або `list=true` | Запитує властивості компілятора чи перелік відповідних типів компонентів; запитує вивід JSON. |
| `runtime_preflight` | `db_connection_name`, `workspace_name` | Визначає та перевіряє налаштування середовища; приймає необов'язковий `app_path`. |
| `runtime_doctor` | `db_connection_name`, `workspace_name` | Діагностує налаштування середовища; приймає необов'язковий `app_path`. |
| `runtime_validate` | `app_path`, `db_connection_name`, `workspace_name` | Перевіряє на сервері; після підтвердженого успіху пропонує окремий інтерактивний шлях імпорту. |

Дві операції безпосередньо змінюють проєкт: створення каркаса та переписування словника. Інші дії також можуть записувати звіти й тимчасові копії середовища. Імпорт на сервер — окрема підтверджена гілка `runtime_validate`.

## Параметри

| Параметр | Тип / значення | Де використовується |
| --- | --- | --- |
| `action` | Одна з дев’яти назв вище | Усі виклики |
| `app_path` | Каталог у межах активного робочого каталогу | Каркас, локальна/компіляторна/серверна перевірка; необов'язковий для preflight/doctor |
| `db_connection_name` | Збережений alias SQLcl, 1–128 символів; латинські літери, цифри, `_`, `.`, `-`; перший символ — літера, цифра або `_` | Probe, каркас, дії середовища |
| `workspace_name` | 1–128 символів; латинські літери, цифри, `_`, `$`, `#`, `.`, `-`; перший символ — літера або цифра | Разом зі збереженим підключенням |
| `execution_mode` | `auto`, `build-root`, `path` | Дії середовища; передається механізму визначення середовища Oracle |
| `apex_root` | Шлях кореня середовища | Дії середовища |
| `compiler_oracle_home` | Каталог метаданих компілятора або Oracle home | Компіляторний аудит, запити властивостей, початкова серверна перевірка |
| `component` | Семантичний ідентифікатор компонента | Запит властивостей |
| `component_type_id` | Числовий ID у вигляді рядка | Запит властивостей |
| `template_component` | Ідентифікатор шаблонного компонента Universal Theme | Запит властивостей |
| `parent`, `group` | Фільтри компонента/групи властивостей | Запит властивостей |
| `when` | Масив до 20 рядків припущень | Запит властивостей |
| `list` | Boolean | Запит властивостей |
| `supporting_objects` | Boolean | Preflight/doctor, перевірка середовища й подальший імпорт |
| `fix_vocab` | Boolean | Локальна перевірка |

Керувальні символи в текстових даних відхиляються. У шляхах також заборонені подвійні лапки й амперсанди. Схема містить спільні необов'язкові поля; побудовник команд визначає, які з них використовує конкретна дія. Зокрема, побудовник roundtrip-імпорту не передає `compiler_oracle_home` як параметр CLI.

## Приклади вхідних даних

Це об'єкти аргументів інструмента, а не shell-команди. Замініть умовні значення перевіреним контекстом проєкту.

```json
{"action":"sqlcl_validate","app_path":"applications/my-app","apex_version":"26.2","sqlcl_bin":"/absolute/path/to/sqlcl/bin/sql"}
```

```json
{"action":"workspace_probe"}
```

```json
{"action":"local_validate","app_path":"applications/service-ops"}
```

```json
{"action":"query_valid_props","list":true}
```

```json
{"action":"runtime_preflight","app_path":"applications/service-ops","db_connection_name":"apex_dev","workspace_name":"SERVICE_OPS_DEV"}
```

```json
{"action":"runtime_validate","app_path":"applications/service-ops","db_connection_name":"apex_dev","workspace_name":"SERVICE_OPS_DEV"}
```

## Результати та критерії успіху

Успішні відповіді інструмента містять текст і `details`, зокрема `action`, `exitCode` та `outputRoot`. Серверна перевірка також повертає `liveValidationPassed` та `imported`, а за потреби — деталі вибору й цілі. Скасовані зміни проєкту повертають `cancelled=true`. Невдалі запуски породжують помилку з доступним виводом процесу та шляхом звітів; помилки вхідних даних до запуску можуть ще не мати звітів.

| Операція | Докази, які перевіряє розширення |
| --- | --- |
| Компіляторна перевірка SQLcl | Код завершення нуль, рівно один явний маркер `Validation successful`, без критичних помилок. Звіт `logs/sqlcl-validate.json` містить `live_check_status=not_run`, `imported=false`. |
| Локальні перевірки | Обгортка успішно завершується й виводить `APEXLANG_LOCAL_CHECK_OK`; окремі звіти містять діагностики. |
| Серверна перевірка | Успішний результат процесу; `live_check_status=pass` **або** `validation_status=pass`; також `validation_sources.live_validator.status=pass`. |
| Доказ відсутності нової цілі | Навмисно заблокований результат: `target_resolution_mode=create-new`, `target_resolution_status=not_found_in_workspace`, `create_new_confirmation_required=true`, `import_status=blocked`, `failure_class=create_new_confirmation_required` і `ok=false`. |
| Імпорт | Успішний результат процесу та `validate_status=pass`, `import_status=pass`, `runtime_gate_status=pass`. |

Самого коду завершення нуль недостатньо для успіху серверної перевірки чи імпорту. Перевірка відсутності нової цілі очікувано зупиняється на межі підтвердження; це ще не імпортований застосунок.

## Сумісність із попередженнями

Адаптер містить окремий шлях сумісності для результатів SQLcl, що містять лише попередження компіляції. Перш ніж нормалізувати результат чи продовжити погоджений імпорт, він перевіряє поточні артефакти, докази в транскрипті та, де потрібно, ідентичність цілі. Відсутні, застарілі, суперечливі докази або докази жорстких помилок залишаються блокувальними. Гілка create-new не використовує резервний шлях сумісності імпорту наявного застосунку.

Цей механізм відокремлений від **рекомендаційної таблиці** ORDS/SQLcl, яка лише додає поради з діагностики. Див. [супровід](maintenance.md) і функції `normalizeWarningOnlyValidation` та `runWarningCompatibleImport` в [адаптері](../../extensions/lib/apexlang-cli.mjs).
