story 2-12-preview-partial-mode: implemented and reviewed via bmad-loop

This commit is contained in:
bsodfather committed 2026-10-03 15:04:15 +03:00
1 parent d1ba0bd0e4
commit ab35d67177
56 files changed
+5801 -376

No files matched your search

+45 -3
View File
@@ -8,11 +8,13 @@ Crank умеет импортировать REST API из OpenAPI 3.x и Swagger
2. Нажмите **Импорт OpenAPI** рядом с кнопкой **Новая операция**.
3. Загрузите ровно один UTF-8 `.yaml`, `.yml` или `.json` файл размером от 1 B до 256 KiB. Вставка текста не поддерживается.
4. Нажмите **Разобрать документ**.
Preview принимает до 2 000 methods; документ с большим числом кандидатов отклоняется целиком с typed ошибкой, без скрытого усечения.
5. Проверьте preview: сгенерированный contract сохраняет parameter locations, body formats, варианты успешного ответа и effective security requirements.
API помечает метод `actionable`, `unresolved` или `blocked` по typed findings и доступным security choices; окончательное разрешение выбранного Auth Profile происходит при создании плана.
6. Выберите нужные группы и методы.
7. Проверьте `Base URL`. Если в документе нет `servers`, укажите URL вручную.
8. Для уже существующей операции подтвердите решение отдельно: пропустить точную операцию, создать отдельную операцию с указанным вами свободным именем или добавить новую черновую версию к выбранной REST-операции. Автоматический подбор имени при применении плана не выполняется.
9. Создайте план и проверьте число выбранных, исключённых, доступных и заблокированных методов. По умолчанию полный план требует, чтобы каждый метод можно было применить; для частичного импорта явно оставьте только нужные методы.
9. Создайте план и проверьте число выбранных, исключённых, доступных и заблокированных методов. По умолчанию действует полный режим: любой blocker запрещает Apply всего документа. Для частичного импорта явно включите режим и выберите только методы без blocker findings с разрешёнными зависимостями и аутентификацией.
10. Для защищённых методов выберите security alternative (OR-варианты preview; неподдерживаемые варианты, включая AND/OAuth, показаны заблокированными) и, если требуется аутентификация, совместимый Auth Profile текущего workspace — по безопасным метаданным `id/name/kind` из preview. Вариант без схем — анонимный вызов без профиля. Статус привязки показывает только API: `Unresolved` до проверки, `Resolved` после подтверждения планом, `Blocked` при отказе; UI не вычисляет resolved локально. Незакрытое обязательное требование или недоступный профиль оставляет метод заблокированным.
11. Подтвердите план и примените его. Создание плана не меняет операции. Применение выполняет все выбранные изменения одной транзакцией и показывает результат для каждого метода.
@@ -26,7 +28,11 @@ Crank умеет импортировать REST API из OpenAPI 3.x и Swagger
При неизвестном результате Apply, например после разрыва соединения, повторите запрос с теми же ссылкой на план, digest и ключом идемпотентности. Повтор после commit возвращает сохранённый отчёт и не создаёт ещё одну версию; тот же ключ с другим digest даёт конфликт. Пока Apply выполняется, повторное нажатие кнопки не отправляет вторую логическую операцию.
Если с момента создания плана изменились источник или внешние документы, версия импортера либо состояние выбранной операции, а также конфигурация выбранного Auth Profile или версия его секрета, Apply отклоняет план без частичных изменений и предлагает заново разобрать документ. Отозванный или недоступный профиль также приводит к отказу. Срок жизни плана ограничен сроком исходного preview job.
Если с момента создания плана изменились источник или внешние документы, версия импортера, workspace catalog либо состояние выбранной операции, а также конфигурация выбранного Auth Profile или версия его секрета, Apply отклоняет план без частичных изменений и предлагает заново разобрать документ. Read-only `GET /api/admin/workspaces/{workspace_id}/imports/openapi/plans/{plan_id}` проверяет сохранённый план при повторном открытии и возвращает `current` или `stale` с `revalidation_required`; проверка не создаёт операции и не делает запрос к изменяемому внешнему `$ref`. Отозванный или недоступный профиль также приводит к отказу. Срок жизни плана ограничен сроком исходного preview job.
Новые планы `import-plan-v2` содержат source/external snapshot digests, версии normalizer/projection и support matrix, catalog revision, полный список кандидатов и selections, findings, решения по конфликтам и причины исключений. Digest вычисляется из semantic material: случайные идентификаторы plan/job/source/новой операции и время создания в него не входят. Сохранённый payload остаётся неизменяемым, а новый выбор или решение создаёт новую запись. Старые `import-plan-v1` продолжают проверяться по исходному полному digest payload.
Workspace catalog для revision и naming читается целиком до 10 000 записей; превышение лимита даёт ошибку вместо усечения. Revision учитывает релевантные метаданные операций, а состояние выбранных Auth Profile и Secret проверяется по безопасным snapshot-метаданным без чтения raw/ciphertext credentials. Для `import-plan-v2` предел сохранённого payload — 16 MiB при общем пределе 2 000 candidates; исторический `import-plan-v1` сохраняет свой предел 4 MiB.
## Что создается
@@ -81,10 +87,46 @@ Semantic loss получает blocker с source location: такой candidate
Один endpoint с несколькими request formats остаётся одним Tool. Поля `content_type` и `body` выбирают одну schema и соответствующую сериализацию; неизвестный selector или body другой ветви отклоняются до отправки запроса. Для единственного формата selector не нужен. Подробный inline-file contract описан в [REST](protocols/rest.md).
Новые imports используют `normalized-ir-v5` / `preview-v5`. Исторические v2/v3/v4 jobs воспроизводят сохранённый preview, а legacy-v1 использует отдельную историческую projection. Обновление importer не меняет inputs существующих jobs.
Новые imports используют `normalized-ir-v5` / `preview-v6`: source-derived candidate, finding и naming conflict включают безопасный RFC 6901 `source_location`; typed findings сохраняют стабильный `code`. Схемы и маппинги принадлежат candidate с его source pointer и проверяемой provenance в IR/reference graph. Производные группы, counts и summary связаны с исходником через membership candidates; единственный pointer или finding code для такой агрегации был бы ложной provenance. Исторические v2/v3/v4/v5 jobs воспроизводят сохранённый preview, а legacy-v1 использует отдельную историческую projection. Обновление importer не меняет inputs существующих jobs.
Другие форматы спецификаций и протоколов в Community-импорт не входят.
## Проверка больших preview на Reference Deployment
Локальная проверка пагинации использует mock API и измеряет только browser handler; она не подтверждает требование AC-11 о полной интерактивности ≤2 s p95. Для операторской проверки нужен отдельный Reference Deployment: Linux x86_64, сервисы с PostgreSQL 16 и Valkey 8 на 4 vCPU/8 GiB, SSD не менее 100 GB, 3000 IOPS и 100 MB/s, LAN не менее 1 Gbit/s, и отдельный эквивалентный load-generator с браузером. Перед запуском сохраните подтверждённые параметры без секретов в JSON-манифесте, например:
```json
{
"deployment": {
"host_id": "reference-server", "cpu_model": "record actual model",
"cpu_cores": 4, "ram_gib": 8, "postgres_version": "16.0",
"valkey_version": "8.0", "storage_type": "SSD",
"ssd_capacity_gb": 100, "ssd_iops": 3000,
"ssd_throughput_mb_s": 100, "lan_mbps": 1000
},
"load_generator": { "host_id": "reference-runner", "cpu_cores": 4, "ram_gib": 8 },
"browser": { "host_id": "reference-runner" }
}
```
На load-generator задайте `PLAYWRIGHT_BASE_URL` для удалённого origin, `PLAYWRIGHT_SKIP_WEB_SERVER=1`, абсолютный путь `CRANK_AC11_REFERENCE_ENV_JSON` и учётные данные через `CRANK_E2E_ADMIN_EMAIL`/`CRANK_E2E_ADMIN_PASSWORD` в окружении; затем выполните из `apps/ui`:
```sh
npx playwright test tests/e2e/openapi-preview-reference.spec.js --workers=1
```
Harness отправляет реальный `openapi.yaml` с 2 000 operations (157 023 B), делает warm-up и 20 независимых preview-запросов без mock routes. Каждый замер начинается при нажатии Preview и заканчивается после ответа API, разбора и отображения первой страницы с доступной кнопкой создания плана. JSON attachment/stdout сохраняет все 20 samples, p95, DOM bound и sanitized сведения об окружении. Отсутствующий URL пропускает только отдельный операторский тест; при заданном URL отсутствующий или неподходящий манифест вызывает ошибку. Сам манифест — декларация оператора; результат требует фактического запуска в указанной инфраструктуре.
Локальное ограниченное evidence: `cd apps/ui && npx playwright test tests/e2e/openapi-preview-partial.spec.js --grep 'AC-11' --workers=1` выводит `AC11_LOCAL_SHARED_HOST_METRICS` с сырыми samples. На shared host Linux x86_64 (Intel Core i5-4300U, 4 logical CPUs), headless Chromium 149, viewport 1280×720, mock fixture 2 000 candidates показал максимум 100 строк preview и 100 строк плана. Время ниже — длительность browser event handlers (`performance.now()`, ms), без API и LAN:
```json
{
"search_filter_ms": [7, 26, 12.7, 9.6, 5.3, 5.2, 6.5, 7.8, 5.5, 7.8, 5.6, 9.8, 8.2, 5.2, 7.9, 11.6, 6.9, 5.3, 6.6, 6],
"preview_page_change_ms": [50.1, 30.1, 23.3, 18.8, 21.3, 24.2, 30, 20.6, 69, 23.9, 22.3, 19.5, 18.8, 20.3, 25.1, 20.8, 20.6, 21.2, 22.4, 24.8],
"plan_page_change_ms": [2.8, 1.9, 1.9, 4.1, 2.9, 3.6, 2.9, 3.9, 2.4, 1.8, 4, 4.7, 1.9, 2, 1.7, 2.1, 1.8, 2.1, 1.7, 3.3]
}
```
## Нормативная матрица и regression corpus
Машинная матрица версии `1.0.2` хранится в [`crates/crank-import/tests/support-matrix.yaml`](../crates/crank-import/tests/support-matrix.yaml); corpus version — `1.0.3`. Матрица фиксирует контракт отдельно для OpenAPI 3.0, OpenAPI 3.1 и Swagger 2.0. Acceptance test запускает нормализатор на отдельном probe для каждой строки, включая все 100 успешных кодов в каждом формате, и сверяет сохранённую semantics или точный blocker; выполненные probes списываются со всех строк версии, поэтому неподвергнутая проверкой строка матрицы падает gate. Версия corpus `1.0.3` добавляет hostile fixture `hostile-security-scope.json`: document-level требование безопасности блокирует только унаследовавшего его secured candidate (`GET /secure`, location `/security/0`), а операция с явным `security: []` (`GET /public`) остаётся actionable без глобального blocker; oversized hostile JSON остаётся тем же canonical JSON с ожидаемым parser rejection.