125 lines
11 KiB
Markdown
125 lines
11 KiB
Markdown
---
|
||
title: '2.7 — Преобразовать OpenAPI в детерминированный NormalizedIR'
|
||
type: 'feature'
|
||
created: '2026-08-29'
|
||
status: 'done'
|
||
baseline_commit: 'bc03c3338768559eaf97f614fceaf9a8c32c3c67'
|
||
review_loop_iteration: 0
|
||
context:
|
||
- '_bmad-output/implementation-artifacts/epic-2-context.md'
|
||
---
|
||
|
||
<frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
|
||
|
||
## Intent
|
||
|
||
**Problem:** `crank-import` сразу проецирует source в Draft-кандидаты, поэтому часть OpenAPI semantics теряется молча, а findings и порядок не имеют устойчивого source contract.
|
||
|
||
**Approach:** Ввести между parsing и preview pure typed `NormalizedIR` с versioned config, stable IDs, coverage ledger и canonical serialization; preview строить adapter-слоем поверх IR.
|
||
|
||
## Boundaries & Constraints
|
||
|
||
**Always:** Формат определяется по содержимому: JSON-first/YAML fallback; версии — только OpenAPI `3.0.x`, `3.1.x`, Swagger `2.0`. Location — RFC 6901 pointer без excerpt; ID выводится из version/method/pointer. Порядок фиксирован. Limits: 256 KiB, depth 64, 50 000 nodes, collection 10 000, aliases 128, scalar 256 KiB. Каждый construct получает typed mapping либо finding. Parser не имеет I/O/domain dependencies. Новые jobs сохраняют normalizer/projection version; legacy jobs сохраняют v1 replay до expiry.
|
||
|
||
**Ask First:** Изменение публичных HTTP-полей 2.1, удаление legacy replay до истечения job TTL, новая production dependency либо перенос semantic mapping из Stories 2.8–2.5.
|
||
|
||
**Never:** Reference I/O; Draft/ImportPlan/domain mutation; silent drop construct; source digest/bytes/parser internals в HTTP; зависимость output от времени, hash-map order, workspace/request IDs.
|
||
|
||
## I/O & Edge-Case Matrix
|
||
|
||
| Scenario | Input / State | Expected Output / Behavior | Error Handling |
|
||
|----------|---------------|---------------------------|----------------|
|
||
| Supported source | Три версии, YAML/JSON | Typed IR: metadata, servers/base path, paths, methods, IDs, tags, schema/ref placeholders, ledger | Ordered findings для неотображаемой semantics |
|
||
| Identity ambiguity | Missing/duplicate `operationId`, reordered maps | Stable `METHOD path` key и canonical suffix по method/path/pointer | Finding связан с construct ID/location |
|
||
| Partial structural defect | Один malformed endpoint среди валидных | Валидные operations остаются в IR | Blocker finding дефектного pointer; Apply остаётся запрещён последующим policy layer |
|
||
| Reference | Local/external/cyclic `$ref` | Typed unresolved reference сохраняет URI/pointer и location, без I/O | Resolution не симулируется и не теряется |
|
||
| Invalid/hostile source | Unsupported/root/no methods/limit excess | Нет пустого success, panic или runaway work | Bounded blocker без raw parser error/source |
|
||
| Replay/concurrency | Те же bytes+digest+config многократно/параллельно | Canonical IR и findings byte-for-byte равны | Version mismatch fail-closed до mutation |
|
||
|
||
</frozen-after-approval>
|
||
|
||
## Code Map
|
||
|
||
- `crates/crank-import/src/rest/model.rs:7-123` — добавить `NormalizedIr`, construct/location, typed spec/schema/ref/coverage; `ImportPreview` оставить redacted projection.
|
||
- `crates/crank-import/src/rest/normalize.rs:21-110` — разделить bounded decode, strict version dispatch, canonical normalization и preview projection; текущий eager `resolve_local_ref` оставить только legacy-v1 path.
|
||
- `crates/crank-import/src/rest/{openapi3.rs,swagger2.rs}` — нормализовать source constructs независимо по endpoint; фиксировать unsupported/invalid semantics findings вместо silent skip.
|
||
- `crates/crank-import/src/rest/{naming.rs,payload.rs,recommendations.rs,schema.rs}` — reuse naming/Draft projection; semantic resolution оставить 2.8–2.5.
|
||
- `crates/crank-import/tests/{unit.rs,fixtures/**}` — заменить узкие inline examples versioned fixture/golden matrix и hostile/determinism regressions.
|
||
- `apps/admin-api/src/service/imports.rs:39-522` — передавать digest/config, сохранять versions/IR fingerprint, одинаково reparse preview/apply без digest в DTO.
|
||
- `apps/admin-api/tests/integration/{openapi_import.rs,openapi_source.rs}` — доказать redaction, parser-version replay, drift fail-closed и отсутствие Draft при blocker/limit errors.
|
||
- `scripts/check-rust-boundaries.py`, `docs/testing-strategy.md` — read-only conventions; `crank-import` остаётся pure crate без registry/artifact/app dependencies.
|
||
|
||
## Tasks & Acceptance
|
||
|
||
**Execution:**
|
||
- [x] `crates/crank-import/src/rest/{model.rs,normalize.rs,openapi3.rs,swagger2.rs,mod.rs}` — bounded typed normalization, stable identity/location, coverage validation и canonical output трёх версий.
|
||
- [x] `crates/crank-import/src/rest/{naming.rs,payload.rs,recommendations.rs,schema.rs}` — построить backward-compatible redacted preview adapter поверх IR и сохранить будущую semantic работу typed placeholders/findings.
|
||
- [x] `crates/crank-import/tests/{unit.rs,fixtures/**}` — добавить YAML/JSON golden fixtures, ordering/duplicate/no-method/partial/ref/limit tests, deterministic generated-property cases и checked-in fuzz regressions.
|
||
- [x] `apps/admin-api/src/service/imports.rs`, `apps/admin-api/tests/integration/{openapi_import.rs,openapi_source.rs}` — version job parser contract, передать artifact digest без HTTP leakage и покрыть rolling replay/reparse/integrity behavior.
|
||
|
||
**Acceptance Criteria:**
|
||
- Given любой supported verified source, when normalization завершается, then каждый распознанный construct присутствует в canonical typed IR либо связан с explicit ordered finding и coverage validator отклоняет gap.
|
||
- Given одинаковые bytes, digest и config, when parser запускается повторно или конкурентно, then serialized IR/findings и public preview совпадают byte-for-byte.
|
||
- Given legacy pending job или новая versioned job, when Apply reparses source после rollout, then используется соответствующая projection version либо запрос fail-closed до Draft mutation без ложного integrity verdict.
|
||
- Given hostile/частично повреждённый документ, when validation срабатывает, then работа bounded, валидные endpoints сохранены, blocker redacted, panic/mutation отсутствуют.
|
||
|
||
## Spec Change Log
|
||
|
||
## Design Notes
|
||
|
||
`NormalizedIR` хранит source identity только для внутренней воспроизводимости; HTTP projection исключает digest. Canonical ordering: path lexical → fixed HTTP method rank → source pointer; findings: severity rank → construct ID → code. Schema composition и references представлены typed source nodes, но разрешаются только следующими Story. Legacy-v1 adapter изолирован и удаляется отдельным решением после максимального TTL.
|
||
|
||
## Verification
|
||
|
||
**Commands:**
|
||
- `cargo test -p crank-import --all-targets` — PASS, 45/45: fixture/property/fuzz-regression matrix, canonical ordering, limits, coverage и legacy replay.
|
||
- `cargo test -p admin-api --test integration -- --test-threads=1` — PASS, 70/70: rolling replay, redaction, parser-contract drift и no-Draft guarantees.
|
||
- `cargo fmt --all -- --check` — PASS.
|
||
- `cargo clippy -p crank-import -p admin-api --all-targets -- -D warnings` — PASS.
|
||
- `just rust-boundaries` — PASS: crate/module/config/migration/metrics/execution boundaries сохранены.
|
||
- `just rust-code-health` — Story 2.7 не добавляет превышений и все её Rust-модули меньше 1000 строк; общий gate остаётся красным только на двух pre-existing Story 2.1 baseline-файлах `crates/crank-artifacts/src/housekeeping.rs` (1119) и `crates/crank-artifacts/tests/artifact_store.rs` (1103), зафиксированных в deferred-work ledger.
|
||
- `git diff --check` — PASS.
|
||
|
||
## Suggested Review Order
|
||
|
||
**Контракт NormalizedIR**
|
||
|
||
- Главная точка входа связывает bounded decode, canonicalization и строгую валидацию.
|
||
[`normalize.rs:82`](../../crates/crank-import/src/rest/normalize.rs#L82)
|
||
|
||
- Versioned типы закрепляют identity, locations, schemas, references и coverage ledger.
|
||
[`model.rs:270`](../../crates/crank-import/src/rest/model.rs#L270)
|
||
|
||
- Coverage validator доказывает отсутствие молча потерянных source constructs.
|
||
[`normalize_coverage.rs:16`](../../crates/crank-import/src/rest/normalize_coverage.rs#L16)
|
||
|
||
**Парсинг и совместимость**
|
||
|
||
- OpenAPI 3 parser сохраняет валидные siblings и локализует malformed semantics.
|
||
[`openapi3.rs:17`](../../crates/crank-import/src/rest/openapi3.rs#L17)
|
||
|
||
- Swagger 2 parser реализует тот же deterministic contract без semantic resolution.
|
||
[`swagger2.rs:17`](../../crates/crank-import/src/rest/swagger2.rs#L17)
|
||
|
||
- Изолированный preview adapter сохраняет публичный DTO и legacy-v1 replay.
|
||
[`normalize.rs:118`](../../crates/crank-import/src/rest/normalize.rs#L118)
|
||
|
||
**Admin apply boundary**
|
||
|
||
- Preview сохраняет parser versions и fingerprint только во внутреннем job payload.
|
||
[`imports.rs:473`](../../apps/admin-api/src/service/imports.rs#L473)
|
||
|
||
- Apply fail-closed сверяет preview, IR fingerprint и parser contract до mutation.
|
||
[`imports.rs:555`](../../apps/admin-api/src/service/imports.rs#L555)
|
||
|
||
**Доказательства**
|
||
|
||
- Recursive pointer test проверяет exact mapping каждого source-tree construct.
|
||
[`coverage.rs:132`](../../crates/crank-import/tests/coverage.rs#L132)
|
||
|
||
- Version/syntax/concurrency matrix подтверждает byte-for-byte детерминизм IR.
|
||
[`unit.rs:426`](../../crates/crank-import/tests/unit.rs#L426)
|
||
|
||
- Integration regression запрещает Draft mutation при operation-level blocker.
|
||
[`openapi_import.rs:510`](../../apps/admin-api/tests/integration/openapi_import.rs#L510)
|