From fbd90d67c6c638f1df63656139cf295348d6d8af Mon Sep 17 00:00:00 2001 From: Marat K Date: Tue, 27 Oct 2026 09:08:45 +0100 Subject: [PATCH 1/2] feat(edit): add native and standalone pure mutations Implement insertion, removal and literal key renaming with textual and segment paths, preserving source ranges and verifying intended semantic trees. Preserve empty ancestors, root trivia, comments, Unicode and source EOL/EOF. Add ABI 2 mutation bindings, source-first transport diagnostics, exception-safe buffer ownership, native/pure regressions and generated EN/RU/ZH documentation. Pin the verified Rust core without changing package versions. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 10 +- CHANGELOG.md | 2 + Cargo.toml | 2 +- README.md | 25 +- crates/cabi/src/lib.rs | 4 +- docs/ru/CHANGELOG.ru.md | 2 + docs/ru/README.ru.md | 25 +- docs/zh/CHANGELOG.zh.md | 2 + docs/zh/README.zh.md | 26 +- root-docs/CHANGELOG/unreleased/body-1.md | 6 + root-docs/README/editing-cookbook/body-1.md | 22 +- root-docs/README/editing-cookbook/body-2.md | 6 - root-docs/README/editing-cookbook/body-3.md | 20 +- root-docs/README/editing-cookbook/body-4.md | 34 +- root-docs/README/editing-cookbook/body-5.md | 43 +- root-docs/README/editing-cookbook/body-6.md | 82 +++ root-docs/README/editing-cookbook/meta.js | 2 +- src/Ktav.php | 67 ++ src/NativeLib.php | 129 +++- src/Pure/Edit/EditEnvelope.php | 12 +- src/Pure/Edit/EditSplice.php | 773 +++++++++++++++++++- src/Pure/Edit/EditTree.php | 57 +- src/PureBackend.php | 36 + tests/MutationNativeSpec.php | 484 ++++++++++++ tests/Pure/InsertMutationSpec.php | 127 ++++ tests/Pure/MutationSpec.php | 187 +++++ 26 files changed, 2032 insertions(+), 153 deletions(-) create mode 100644 root-docs/README/editing-cookbook/body-6.md create mode 100644 tests/MutationNativeSpec.php create mode 100644 tests/Pure/InsertMutationSpec.php create mode 100644 tests/Pure/MutationSpec.php diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 97a7bf5..b9b5c68 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -116,18 +116,18 @@ jobs: # Provenance (release guards NOT weakened — the target moved): # Cargo.lock is generated in CI, NOT committed. The ktav core is # the IMMUTABLE GIT PIN chosen by the user for the 0.9 - # source-edit ABI (rev 447a00bd012e8d3f347c7e1eb59c3f0d9a78332f); + # source-edit/mutation ABI (rev 8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910); # the TOML parse must show exactly one ktav [[package]] whose # source is that exact git rev — a registry swap, a local-path # override, a moved rev or a different branch fails the job here. - - name: Generate Cargo.lock and verify the immutable ktav git-core pin (447a00b, ABI 2) + - name: Generate Cargo.lock and verify the immutable ktav git-core pin (8b6b45f, ABI 2) shell: bash run: | set -e cargo generate-lockfile python3 - <<'PY' import sys, tomllib - REV = '447a00bd012e8d3f347c7e1eb59c3f0d9a78332f' + REV = '8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910' with open('Cargo.lock', 'rb') as f: data = tomllib.load(f) pkgs = [p for p in data.get('package', []) if p.get('name') == 'ktav'] @@ -150,8 +150,8 @@ jobs: with open('Cargo.toml', 'rb') as f: ws = tomllib.load(f) ktav = ws['workspace']['dependencies']['ktav'] - if ktav.get('git') != 'https://github.com/ktav-lang/rust' or ktav.get('rev') != '447a00bd012e8d3f347c7e1eb59c3f0d9a78332f': - sys.exit('workspace ktav dependency is not the immutable 447a00b pin: %r' % (ktav,)) + if ktav.get('git') != 'https://github.com/ktav-lang/rust' or ktav.get('rev') != '8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910': + sys.exit('workspace ktav dependency is not the immutable 8b6b45f pin: %r' % (ktav,)) print('workspace ktav dependency pinned:', ktav['rev']) PY diff --git a/CHANGELOG.md b/CHANGELOG.md index a878d13..6dfd325 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,8 @@ itself — for the latter see ## Unreleased +- PHP source mutation now includes insert, remove and rename in both native and standalone pure backends. Insert adds a new final Object key without overwriting; remove targets an existing Object member or Array element without pruning ancestors (later Array elements shift); rename requires an existing final Object member and an absent destination key in that Object, preserving position and value. Insert requires an existing parent Object; Array insertion is unsupported. Native uses ABI 2 and the verified Rust core pin `8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910`; package versions remain unchanged and this unreleased 0.9 functionality is not part of published 0.8.1. + ### 0.8.1 #### Added diff --git a/Cargo.toml b/Cargo.toml index 0b8992c..e1a1797 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,7 +11,7 @@ rust-version = "1.71" [workspace.dependencies] # Подготовка 0.9: immutable core pin с source-edit и ABI 2; пакет ещё не опубликован. -ktav = { git = "https://github.com/ktav-lang/rust", rev = "447a00bd012e8d3f347c7e1eb59c3f0d9a78332f" } +ktav = { git = "https://github.com/ktav-lang/rust", rev = "8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910" } serde = { version = "1", features = ["derive"] } serde_json = { version = "1", features = ["preserve_order"] } indexmap = "2" diff --git a/README.md b/README.md index dd9842e..26e90a0 100644 --- a/README.md +++ b/README.md @@ -179,19 +179,18 @@ stay ordered. ### Source-edit cookbook -These examples describe the unreleased 0.9 API, not the published 0.8.1 package. They replace existing values only: keys are not renamed, missing paths are not created, and entries are not removed. Each snippet is independent; Rust `?` assumes an enclosing `Result`-returning function. Go examples panic only for these fixed, known-valid inputs; applications should handle the returned error. +These examples describe the unreleased 0.9 API, not the published 0.8.1 package. Value replacement and insert/remove/rename are available through both pure and native backends. Each snippet is independent; Rust `?` assumes an enclosing `Result`-returning function. Go examples panic only for these fixed, known-valid inputs; applications should handle the returned error. The binding examples use the standalone pure backend, without a native binary. Native entry points accept the same paths and values: `ktav.EditValue` (Go), `Ktav.editValue` (Java), `KtavApi.EditValue(..., KtavBackend.Native)` (C#), `Ktav::editValue` (PHP), the package's native/FFI exports (JS), and `ktav.edit_value` (Python). C-ABI backends require ABI 2; PyO3/N-API/WASM require the matching preparing-0.9 core. Bun/Deno FFI calls return promises: use `await`; pure/Node/WASM examples shown here are synchronous. -```php -use Ktav\PureBackend; -``` +Use `PureBackend` or the native backend (`Ktav::`) for value replacement, insertion, removal, and renaming; both backends follow the same mutation contract. Textual paths split on dots, with `\.` for a literal dot and `\\` for a literal backslash; segment variants take decoded literal path segments. For rename, `newKey` is one decoded key, not a path. Bun/Deno FFI calls return promises and require `await`. #### 1. Dotted deployment settings Only the address changes; the comment, dotted form and neighbouring user entry remain byte-for-byte unchanged. ```php +use Ktav\PureBackend; $source = "## deployment\ntargets.storagehost.address: old\ntargets.storagehost.user: mcp-agent\n"; $updated = PureBackend::editValue($source, "targets.storagehost.address", "192.168.0.88:22"); ``` @@ -292,6 +291,7 @@ n : +1 The returned string keeps the BOM and CRLF, and does not gain a final newline. Its escaped representation is shown to make the bytes visible. ```php +use Ktav\PureBackend; $source = "\u{FEFF}port: 8080\r\nhost: db"; $updated = PureBackend::editValue($source, "port", 9090); ``` @@ -316,6 +316,23 @@ $updated = PureBackend::editValue("n: 1\n", "n", ['$i' => '9007199254740993']); n: 9007199254740993 ``` +#### 9. Insert, remove and rename (textual and segment paths) + +These new 0.9 insert/remove/rename operations are available through both pure and native backends and follow the same mutation contract. Insert adds a new final Object key without overwriting; removal targets an existing Object member or Array element without pruning ancestors (later Array elements shift); renaming requires an existing final Object member and a destination key absent from that same Object, preserving position and value. Insertion requires an existing parent Object; insertion into an Array is unsupported. Missing targets and invalid path/segment inputs are errors. Textual paths split on dots, with `\.` for a literal dot and `\\` for a literal backslash. Segment variants accept decoded literal path segments. `newKey` is one decoded key, not a path. Each snippet is independent. + +```php +use Ktav\PureBackend; +$source = 'settings: {old: 1, "a.b": 3}' . "\n"; +$inserted = PureBackend::insertValue($source, "settings.new", 2); +$insertedLiteral = PureBackend::insertValueSegments($source, ["settings", "added"], 2); +$removed = PureBackend::removeValue($source, "settings.old"); +$removedLiteral = PureBackend::removeValueSegments($source, ["settings", "a.b"]); +$renamed = PureBackend::renameKey($source, "settings.old", "new.name"); +$renamedLiteral = PureBackend::renameKeySegments($source, ["settings", "old"], "new.name"); +``` + +An existing insertion key is an error, not an overwrite. Array elements shift after removal. Structural edits to containers with interior comments are unsupported because comments cannot be preserved losslessly. Inline dotted syntax is supported for value replacement, but structural insert/remove/rename requiring a synthetic, noncontiguous dotted path is unsupported. A trailing comma is preserved when the edit can be represented losslessly; the editor does not prune empty ancestors or promise lossless rewriting for every structural layout. + ### Diagnostics and safe failures in 0.9 Source coordinates are UTF-8 byte offsets, including a BOM; spans are half-open `[start, end)`, and lines are 1-based. LF, lone CR and CRLF are handled, with CRLF counted as one terminator. A Unicode character may occupy several bytes. diff --git a/crates/cabi/src/lib.rs b/crates/cabi/src/lib.rs index c9f7b90..2192a91 100644 --- a/crates/cabi/src/lib.rs +++ b/crates/cabi/src/lib.rs @@ -5,7 +5,9 @@ //! PHP consumer loads via `FFI::cdef`: `ktav_loads`, `ktav_loads_strict`, //! `ktav_dumps`, `ktav_dumps_force_strings`, `ktav_emit_canonical`, //! `ktav_format`, `ktav_canonical_from_source`, `ktav_free`, -//! `ktav_version` and `ktav_abi_version`. Same signatures, ownership +//! `ktav_insert_value`, `ktav_insert_value_segments`, `ktav_remove_value`, +//! `ktav_remove_value_segments`, `ktav_rename_key`, `ktav_rename_key_segments`, +//! `ktav_free`, `ktav_version` and `ktav_abi_version`. //! contract (`ktav_free(ptr, len)` frees exactly what a `ktav_*` call //! returned), `0`/`1` return codes and JSON error envelopes as the //! handwritten shim this crate carried before ktav 0.8. The wire format diff --git a/docs/ru/CHANGELOG.ru.md b/docs/ru/CHANGELOG.ru.md index 889bb1e..37f9e2e 100644 --- a/docs/ru/CHANGELOG.ru.md +++ b/docs/ru/CHANGELOG.ru.md @@ -23,6 +23,8 @@ MINOR — ломающий. ## Unreleased +- Мутации исходника PHP теперь включают вставку, удаление и переименование как в native-, так и в самостоятельном pure-бэкенде. Вставка добавляет новый последний ключ Object без перезаписи; удаление затрагивает существующий член Object или элемент Array, не удаляя предков (последующие элементы Array сдвигаются); переименование требует существующий последний член Object и отсутствующий целевой ключ в этом Object, сохраняя позицию и значение. Для вставки нужен существующий родительский Object; вставка в Array не поддерживается. Native использует ABI 2 и проверенный pin ядра Rust `8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910`; версии пакетов не меняются, эта ещё не выпущенная функциональность 0.9 не входит в опубликованный 0.8.1. + ### 0.8.1 #### Добавлено diff --git a/docs/ru/README.ru.md b/docs/ru/README.ru.md index 60a6098..6e7d7eb 100644 --- a/docs/ru/README.ru.md +++ b/docs/ru/README.ru.md @@ -181,19 +181,18 @@ Object ИГНОРИРУЕТ порядок ключей (Rust IndexMap PartialEq ### Практические примеры правки исходника -Примеры относятся к ещё не выпущенному API 0.9, а не к опубликованному пакету 0.8.1. Они заменяют только существующие значения: не переименовывают ключи, не создают отсутствующие пути и не удаляют записи. Фрагменты независимы; Rust `?` предполагает внешнюю функцию с результатом `Result`. В Go panic используется только для фиксированных корректных данных примера; приложение должно обработать возвращённую ошибку. +Замена значений и операции вставки, удаления и переименования доступны через pure- и native-бэкенды. Примеры относятся к ещё не выпущенному API 0.9, а не к опубликованному пакету 0.8.1. Фрагменты независимы; Rust `?` предполагает внешнюю функцию с результатом `Result`. В Go panic используется только для фиксированных корректных данных примера; приложение должно обработать возвращённую ошибку. Примеры привязок используют самостоятельный pure-бэкенд без native-бинарника. Нативные точки входа принимают те же пути и значения: `ktav.EditValue` (Go), `Ktav.editValue` (Java), `KtavApi.EditValue(..., KtavBackend.Native)` (C#), `Ktav::editValue` (PHP), native/FFI-экспорты пакета (JS), `ktav.edit_value` (Python). C ABI требует версию 2; PyO3/N-API/WASM — совместимое ядро подготовки 0.9. FFI-вызовы Bun/Deno возвращают promise и требуют `await`; показанные pure/Node/WASM-варианты синхронны. -```php -use Ktav\PureBackend; -``` +Для замены значения и операций вставки, удаления и переименования используйте `PureBackend` или native-бэкенд (`Ktav::`); оба бэкенда следуют одному контракту изменений. Текстовые пути разделяются по точкам; `\.` задаёт буквальную точку, а `\\` — буквальную обратную косую черту. Сегментные варианты принимают декодированные буквальные сегменты пути. При переименовании `newKey` — один декодированный ключ, а не путь. FFI-вызовы Bun/Deno возвращают promise и требуют `await`. #### 1. Настройка развёртывания через dotted-ключ Меняется только адрес; комментарий, dotted-форма и соседнее поле пользователя сохраняются байт-в-байт. ```php +use Ktav\PureBackend; $source = "## deployment\ntargets.storagehost.address: old\ntargets.storagehost.user: mcp-agent\n"; $updated = PureBackend::editValue($source, "targets.storagehost.address", "192.168.0.88:22"); ``` @@ -294,6 +293,7 @@ n : +1 Результат сохраняет BOM и CRLF, не добавляя финальный перевод строки. Экранированное представление делает эти байты видимыми. ```php +use Ktav\PureBackend; $source = "\u{FEFF}port: 8080\r\nhost: db"; $updated = PureBackend::editValue($source, "port", 9090); ``` @@ -318,6 +318,23 @@ $updated = PureBackend::editValue("n: 1\n", "n", ['$i' => '9007199254740993']); n: 9007199254740993 ``` +#### 9. Вставка, удаление и переименование (текстовые пути и сегменты) + +Новые операции вставки, удаления и переименования API 0.9 доступны через pure- и native-бэкенды и следуют одному контракту изменений. Вставка добавляет новый последний ключ Object без перезаписи; удаление удаляет существующий член Object или элемент Array, не удаляя предков (последующие элементы Array сдвигаются); переименование требует существующий последний член Object и отсутствующий целевой ключ в том же Object, сохраняя позицию и значение. Для вставки родительский путь должен вести к существующему Object; вставка в Array не поддерживается. Отсутствующие цели и некорректный ввод путей/сегментов завершаются ошибкой. Текстовый путь разделяется по точкам; `\.` задаёт буквальную точку, `\\` — буквальную обратную косую черту. Сегментные варианты принимают декодированные буквальные сегменты пути. `newKey` — один декодированный ключ, а не путь. Каждый пример независим. + +```php +use Ktav\PureBackend; +$source = 'settings: {old: 1, "a.b": 3}' . "\n"; +$inserted = PureBackend::insertValue($source, "settings.new", 2); +$insertedLiteral = PureBackend::insertValueSegments($source, ["settings", "added"], 2); +$removed = PureBackend::removeValue($source, "settings.old"); +$removedLiteral = PureBackend::removeValueSegments($source, ["settings", "a.b"]); +$renamed = PureBackend::renameKey($source, "settings.old", "new.name"); +$renamedLiteral = PureBackend::renameKeySegments($source, ["settings", "old"], "new.name"); +``` + +Вставка при существующем ключе завершается ошибкой, а не перезаписью. Элементы Array после удаления сдвигаются. Структурные изменения контейнеров с внутренними комментариями не поддерживаются, поскольку комментарии нельзя сохранить без потерь. Встроенная dotted-форма поддерживается для замены значения, но структурные вставка/удаление/переименование, требующие синтетического непоследовательного dotted-пути, не поддерживаются. Конечная запятая сохраняется, если изменение можно представить без потерь; редактор не удаляет пустых предков и не гарантирует без потерь переписывать любую структурную раскладку. + ### Диагностика и безопасные отказы в 0.9 Координаты исходника — байтовые смещения UTF-8 с учётом BOM; spans полуоткрыты `[start, end)`, строки нумеруются с 1. Поддерживаются LF, отдельный CR и CRLF; CRLF считается одним переводом строки. Один Unicode-символ может занимать несколько байтов. diff --git a/docs/zh/CHANGELOG.zh.md b/docs/zh/CHANGELOG.zh.md index 2ea9ba7..846a6d6 100644 --- a/docs/zh/CHANGELOG.zh.md +++ b/docs/zh/CHANGELOG.zh.md @@ -23,6 +23,8 @@ MINOR 递增即破坏性变更。 ## Unreleased +- PHP 源文本修改现已在 native 和独立 pure 后端中支持插入、删除及重命名。插入会添加新的最后一个 Object 键而不覆盖已有键;删除现有 Object 成员或 Array 元素但保留祖先(后续 Array 元素会移位);重命名要求最后一个 Object 成员存在且同一 Object 中目标键不存在,同时保留位置和值。插入要求父级是现有 Object;不支持向 Array 插入。Native 使用 ABI 2 及已验证的 Rust 核心 pin `8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910`;包版本不变,这些尚未发布的 0.9 功能不属于已发布的 0.8.1。 + ### 0.8.1 #### 新增 diff --git a/docs/zh/README.zh.md b/docs/zh/README.zh.md index fb59340..73d3159 100644 --- a/docs/zh/README.zh.md +++ b/docs/zh/README.zh.md @@ -166,19 +166,18 @@ Integer 身份是精确的数字串比较,Float 身份是精确的 f64 比较 ### 源文本编辑示例 -以下示例适用于尚未发布的 0.9 API,而非已发布的 0.8.1 包。只能替换已有值:不会重命名键、创建缺失路径或删除条目。各代码片段相互独立;Rust 的 `?` 假定外层函数返回 `Result`。Go 示例仅针对固定且有效的输入使用 panic;应用程序应处理返回的错误。 +以下示例适用于尚未发布的 0.9 API,而非已发布的 0.8.1 包。值替换以及插入、删除和重命名操作可通过 pure 和 native 后端使用。各代码片段相互独立;Rust 的 `?` 假定外层函数返回 `Result`。Go 示例仅针对固定且有效的输入使用 panic;应用程序应处理返回的错误。 绑定示例使用无需原生二进制的独立纯实现。原生入口接收相同的路径和值:Go 的 `ktav.EditValue`、Java 的 `Ktav.editValue`、C# 的 `KtavApi.EditValue(..., KtavBackend.Native)`、PHP 的 `Ktav::editValue`、JS 包的 native/FFI 导出及 Python 的 `ktav.edit_value`。C ABI 后端要求 ABI 2;PyO3/N-API/WASM 要求兼容的 0.9 准备核心。Bun/Deno FFI 返回 promise,需要 `await`;此处 pure/Node/WASM 示例为同步调用。 -```php -use Ktav\PureBackend; -``` +值替换以及插入、删除和重命名操作可使用 `PureBackend` 或 native 后端(`Ktav::`);两种后端遵循相同的修改契约。文本路径按点拆分;`\.` 表示字面点,`\\` 表示字面反斜杠。路径段变体接收已解码的字面路径段。重命名时,`newKey` 是单个已解码键名,而非路径。Bun/Deno FFI 调用返回 promise,需要 `await`。 #### 1. 通过点分键修改部署配置 只修改地址;注释、点分形式及相邻的用户字段逐字节保持不变。 ```php +use Ktav\PureBackend; $source = "## deployment\ntargets.storagehost.address: old\ntargets.storagehost.user: mcp-agent\n"; $updated = PureBackend::editValue($source, "targets.storagehost.address", "192.168.0.88:22"); ``` @@ -190,7 +189,6 @@ $updated = PureBackend::editValue($source, "targets.storagehost.address", "192.1 targets.storagehost.address: 192.168.0.88:22 targets.storagehost.user: mcp-agent ``` - #### 2. 字面点号:文本路径或路径段 源码中带引号的键名就是 `a.b`。文本路径需要转义点号;路径段 API 直接接收解码后的键名。两个调用返回相同结果。 @@ -279,6 +277,7 @@ n : +1 返回值保留 BOM 和 CRLF,且不会增加末尾换行。以下转义表示使这些字节清晰可见。 ```php +use Ktav\PureBackend; $source = "\u{FEFF}port: 8080\r\nhost: db"; $updated = PureBackend::editValue($source, "port", 9090); ``` @@ -303,6 +302,23 @@ $updated = PureBackend::editValue("n: 1\n", "n", ['$i' => '9007199254740993']); n: 9007199254740993 ``` +#### 9. 插入、删除和重命名(文本路径和路径段) + +新的 0.9 插入、删除和重命名操作可通过 pure 和 native 后端使用,并遵循相同的修改契约。插入会添加新的最后一个 Object 键而不覆盖已有键;删除现有 Object 成员或 Array 元素但保留其祖先(后续 Array 元素会移位);重命名要求最后一个 Object 成员存在,且同一 Object 中目标键不存在,同时保留其位置和值。插入路径的父级必须指向现有 Object;不支持向 Array 插入。目标不存在或路径/路径段输入无效时会报错。文本路径按点拆分;`\.` 表示字面点,`\\` 表示字面反斜杠。路径段变体接收已解码的字面路径段。`newKey` 是单个已解码键名,而非路径。每个代码片段相互独立。 + +```php +use Ktav\PureBackend; +$source = 'settings: {old: 1, "a.b": 3}' . "\n"; +$inserted = PureBackend::insertValue($source, "settings.new", 2); +$insertedLiteral = PureBackend::insertValueSegments($source, ["settings", "added"], 2); +$removed = PureBackend::removeValue($source, "settings.old"); +$removedLiteral = PureBackend::removeValueSegments($source, ["settings", "a.b"]); +$renamed = PureBackend::renameKey($source, "settings.old", "new.name"); +$renamedLiteral = PureBackend::renameKeySegments($source, ["settings", "old"], "new.name"); +``` + +插入时若键已存在会报错,不会覆盖。删除后 Array 元素会移位。由于无法无损保留注释,不支持对内部含注释的容器进行结构编辑。行内点分语法支持值替换,但需要合成非连续点分路径的结构插入/删除/重命名不受支持。若编辑可无损表示,则保留末尾逗号;编辑器不会清除空祖先,也不保证所有结构布局都能无损重写。 + ### 0.9 的诊断与安全失败 源码坐标为包含 BOM 的 UTF-8 字节偏移,span 使用半开区间 `[start, end)`,行号从 1 开始。支持 LF、独立 CR 和 CRLF,且 CRLF 计为一个换行。一个 Unicode 字符可能占用多个字节。 diff --git a/root-docs/CHANGELOG/unreleased/body-1.md b/root-docs/CHANGELOG/unreleased/body-1.md index 63934f5..e4b630c 100644 --- a/root-docs/CHANGELOG/unreleased/body-1.md +++ b/root-docs/CHANGELOG/unreleased/body-1.md @@ -1,6 +1,8 @@ >>>>> lang=en ## Unreleased +- PHP source mutation now includes insert, remove and rename in both native and standalone pure backends. Insert adds a new final Object key without overwriting; remove targets an existing Object member or Array element without pruning ancestors (later Array elements shift); rename requires an existing final Object member and an absent destination key in that Object, preserving position and value. Insert requires an existing parent Object; Array insertion is unsupported. Native uses ABI 2 and the verified Rust core pin `8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910`; package versions remain unchanged and this unreleased 0.9 functionality is not part of published 0.8.1. + ### 0.8.1 #### Added @@ -26,6 +28,8 @@ >>>>> lang=ru ## Unreleased +- Мутации исходника PHP теперь включают вставку, удаление и переименование как в native-, так и в самостоятельном pure-бэкенде. Вставка добавляет новый последний ключ Object без перезаписи; удаление затрагивает существующий член Object или элемент Array, не удаляя предков (последующие элементы Array сдвигаются); переименование требует существующий последний член Object и отсутствующий целевой ключ в этом Object, сохраняя позицию и значение. Для вставки нужен существующий родительский Object; вставка в Array не поддерживается. Native использует ABI 2 и проверенный pin ядра Rust `8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910`; версии пакетов не меняются, эта ещё не выпущенная функциональность 0.9 не входит в опубликованный 0.8.1. + ### 0.8.1 #### Добавлено @@ -51,6 +55,8 @@ >>>>> lang=zh ## Unreleased +- PHP 源文本修改现已在 native 和独立 pure 后端中支持插入、删除及重命名。插入会添加新的最后一个 Object 键而不覆盖已有键;删除现有 Object 成员或 Array 元素但保留祖先(后续 Array 元素会移位);重命名要求最后一个 Object 成员存在且同一 Object 中目标键不存在,同时保留位置和值。插入要求父级是现有 Object;不支持向 Array 插入。Native 使用 ABI 2 及已验证的 Rust 核心 pin `8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910`;包版本不变,这些尚未发布的 0.9 功能不属于已发布的 0.8.1。 + ### 0.8.1 #### 新增 diff --git a/root-docs/README/editing-cookbook/body-1.md b/root-docs/README/editing-cookbook/body-1.md index c64aa12..0e73883 100644 --- a/root-docs/README/editing-cookbook/body-1.md +++ b/root-docs/README/editing-cookbook/body-1.md @@ -1,19 +1,18 @@ >>>>> lang=en ### Source-edit cookbook -These examples describe the unreleased 0.9 API, not the published 0.8.1 package. They replace existing values only: keys are not renamed, missing paths are not created, and entries are not removed. Each snippet is independent; Rust `?` assumes an enclosing `Result`-returning function. Go examples panic only for these fixed, known-valid inputs; applications should handle the returned error. +These examples describe the unreleased 0.9 API, not the published 0.8.1 package. Value replacement and insert/remove/rename are available through both pure and native backends. Each snippet is independent; Rust `?` assumes an enclosing `Result`-returning function. Go examples panic only for these fixed, known-valid inputs; applications should handle the returned error. The binding examples use the standalone pure backend, without a native binary. Native entry points accept the same paths and values: `ktav.EditValue` (Go), `Ktav.editValue` (Java), `KtavApi.EditValue(..., KtavBackend.Native)` (C#), `Ktav::editValue` (PHP), the package's native/FFI exports (JS), and `ktav.edit_value` (Python). C-ABI backends require ABI 2; PyO3/N-API/WASM require the matching preparing-0.9 core. Bun/Deno FFI calls return promises: use `await`; pure/Node/WASM examples shown here are synchronous. -```php -use Ktav\PureBackend; -``` +Use `PureBackend` or the native backend (`Ktav::`) for value replacement, insertion, removal, and renaming; both backends follow the same mutation contract. Textual paths split on dots, with `\.` for a literal dot and `\\` for a literal backslash; segment variants take decoded literal path segments. For rename, `newKey` is one decoded key, not a path. Bun/Deno FFI calls return promises and require `await`. #### 1. Dotted deployment settings Only the address changes; the comment, dotted form and neighbouring user entry remain byte-for-byte unchanged. ```php +use Ktav\PureBackend; $source = "## deployment\ntargets.storagehost.address: old\ntargets.storagehost.user: mcp-agent\n"; $updated = PureBackend::editValue($source, "targets.storagehost.address", "192.168.0.88:22"); ``` @@ -29,19 +28,18 @@ targets.storagehost.user: mcp-agent >>>>> lang=ru ### Практические примеры правки исходника -Примеры относятся к ещё не выпущенному API 0.9, а не к опубликованному пакету 0.8.1. Они заменяют только существующие значения: не переименовывают ключи, не создают отсутствующие пути и не удаляют записи. Фрагменты независимы; Rust `?` предполагает внешнюю функцию с результатом `Result`. В Go panic используется только для фиксированных корректных данных примера; приложение должно обработать возвращённую ошибку. +Замена значений и операции вставки, удаления и переименования доступны через pure- и native-бэкенды. Примеры относятся к ещё не выпущенному API 0.9, а не к опубликованному пакету 0.8.1. Фрагменты независимы; Rust `?` предполагает внешнюю функцию с результатом `Result`. В Go panic используется только для фиксированных корректных данных примера; приложение должно обработать возвращённую ошибку. Примеры привязок используют самостоятельный pure-бэкенд без native-бинарника. Нативные точки входа принимают те же пути и значения: `ktav.EditValue` (Go), `Ktav.editValue` (Java), `KtavApi.EditValue(..., KtavBackend.Native)` (C#), `Ktav::editValue` (PHP), native/FFI-экспорты пакета (JS), `ktav.edit_value` (Python). C ABI требует версию 2; PyO3/N-API/WASM — совместимое ядро подготовки 0.9. FFI-вызовы Bun/Deno возвращают promise и требуют `await`; показанные pure/Node/WASM-варианты синхронны. -```php -use Ktav\PureBackend; -``` +Для замены значения и операций вставки, удаления и переименования используйте `PureBackend` или native-бэкенд (`Ktav::`); оба бэкенда следуют одному контракту изменений. Текстовые пути разделяются по точкам; `\.` задаёт буквальную точку, а `\\` — буквальную обратную косую черту. Сегментные варианты принимают декодированные буквальные сегменты пути. При переименовании `newKey` — один декодированный ключ, а не путь. FFI-вызовы Bun/Deno возвращают promise и требуют `await`. #### 1. Настройка развёртывания через dotted-ключ Меняется только адрес; комментарий, dotted-форма и соседнее поле пользователя сохраняются байт-в-байт. ```php +use Ktav\PureBackend; $source = "## deployment\ntargets.storagehost.address: old\ntargets.storagehost.user: mcp-agent\n"; $updated = PureBackend::editValue($source, "targets.storagehost.address", "192.168.0.88:22"); ``` @@ -57,19 +55,18 @@ targets.storagehost.user: mcp-agent >>>>> lang=zh ### 源文本编辑示例 -以下示例适用于尚未发布的 0.9 API,而非已发布的 0.8.1 包。只能替换已有值:不会重命名键、创建缺失路径或删除条目。各代码片段相互独立;Rust 的 `?` 假定外层函数返回 `Result`。Go 示例仅针对固定且有效的输入使用 panic;应用程序应处理返回的错误。 +以下示例适用于尚未发布的 0.9 API,而非已发布的 0.8.1 包。值替换以及插入、删除和重命名操作可通过 pure 和 native 后端使用。各代码片段相互独立;Rust 的 `?` 假定外层函数返回 `Result`。Go 示例仅针对固定且有效的输入使用 panic;应用程序应处理返回的错误。 绑定示例使用无需原生二进制的独立纯实现。原生入口接收相同的路径和值:Go 的 `ktav.EditValue`、Java 的 `Ktav.editValue`、C# 的 `KtavApi.EditValue(..., KtavBackend.Native)`、PHP 的 `Ktav::editValue`、JS 包的 native/FFI 导出及 Python 的 `ktav.edit_value`。C ABI 后端要求 ABI 2;PyO3/N-API/WASM 要求兼容的 0.9 准备核心。Bun/Deno FFI 返回 promise,需要 `await`;此处 pure/Node/WASM 示例为同步调用。 -```php -use Ktav\PureBackend; -``` +值替换以及插入、删除和重命名操作可使用 `PureBackend` 或 native 后端(`Ktav::`);两种后端遵循相同的修改契约。文本路径按点拆分;`\.` 表示字面点,`\\` 表示字面反斜杠。路径段变体接收已解码的字面路径段。重命名时,`newKey` 是单个已解码键名,而非路径。Bun/Deno FFI 调用返回 promise,需要 `await`。 #### 1. 通过点分键修改部署配置 只修改地址;注释、点分形式及相邻的用户字段逐字节保持不变。 ```php +use Ktav\PureBackend; $source = "## deployment\ntargets.storagehost.address: old\ntargets.storagehost.user: mcp-agent\n"; $updated = PureBackend::editValue($source, "targets.storagehost.address", "192.168.0.88:22"); ``` @@ -81,4 +78,5 @@ $updated = PureBackend::editValue($source, "targets.storagehost.address", "192.1 targets.storagehost.address: 192.168.0.88:22 targets.storagehost.user: mcp-agent ``` +#### 2. 字面点号:文本路径或路径段 diff --git a/root-docs/README/editing-cookbook/body-2.md b/root-docs/README/editing-cookbook/body-2.md index 43c5be8..6502a07 100644 --- a/root-docs/README/editing-cookbook/body-2.md +++ b/root-docs/README/editing-cookbook/body-2.md @@ -24,8 +24,6 @@ $source = "servers: [{host: old, keep: yes}, standby]\n"; $updated = PureBackend::editValueSegments($source, ["servers", "0", "host"], "new"); ``` -Result: - >>>>> lang=ru #### 2. Буквальные точки: текстовый путь или сегменты @@ -52,11 +50,7 @@ $source = "servers: [{host: old, keep: yes}, standby]\n"; $updated = PureBackend::editValueSegments($source, ["servers", "0", "host"], "new"); ``` -Результат: - >>>>> lang=zh -#### 2. 字面点号:文本路径或路径段 - 源码中带引号的键名就是 `a.b`。文本路径需要转义点号;路径段 API 直接接收解码后的键名。两个调用返回相同结果。 ```php diff --git a/root-docs/README/editing-cookbook/body-3.md b/root-docs/README/editing-cookbook/body-3.md index 89e0bbd..d89ec8b 100644 --- a/root-docs/README/editing-cookbook/body-3.md +++ b/root-docs/README/editing-cookbook/body-3.md @@ -1,4 +1,6 @@ >>>>> lang=en +Result: + ```ktav servers: [{host: new, keep: yes}, standby] ``` @@ -22,14 +24,9 @@ port:: 9090 The changed array expands with four-space indentation. The untouched object stays inline, and verbatim string contents are not reindented. -```php -$source = "a: [old, {keep: yes}]\n"; -$updated = PureBackend::editValue($source, "a.0", "x\ny"); -``` - -Result: - >>>>> lang=ru +Результат: + ```ktav servers: [{host: new, keep: yes}, standby] ``` @@ -53,13 +50,6 @@ port:: 9090 Изменённый массив раскрывается с отступом четыре пробела. Нетронутый объект остаётся inline, содержимое verbatim-строки не переотступается. -```php -$source = "a: [old, {keep: yes}]\n"; -$updated = PureBackend::editValue($source, "a.0", "x\ny"); -``` - -Результат: - >>>>> lang=zh ```ktav servers: [{host: new, keep: yes}, standby] @@ -89,5 +79,3 @@ $source = "a: [old, {keep: yes}]\n"; $updated = PureBackend::editValue($source, "a.0", "x\ny"); ``` -结果: - diff --git a/root-docs/README/editing-cookbook/body-4.md b/root-docs/README/editing-cookbook/body-4.md index 614fb1a..f953e6a 100644 --- a/root-docs/README/editing-cookbook/body-4.md +++ b/root-docs/README/editing-cookbook/body-4.md @@ -1,4 +1,11 @@ >>>>> lang=en +```php +$source = "a: [old, {keep: yes}]\n"; +$updated = PureBackend::editValue($source, "a.0", "x\ny"); +``` + +Result: + ```ktav a: [ (( @@ -19,15 +26,14 @@ $updated = PureBackend::editValue($source, "n", 1); assert($updated === $source); ``` -Result: - -```ktav -n : +1 +>>>>> lang=ru +```php +$source = "a: [old, {keep: yes}]\n"; +$updated = PureBackend::editValue($source, "a.0", "x\ny"); ``` -#### 7. BOM, CRLF and an unterminated final line +Результат: ->>>>> lang=ru ```ktav a: [ (( @@ -48,15 +54,9 @@ $updated = PureBackend::editValue($source, "n", 1); assert($updated === $source); ``` -Результат: - -```ktav -n : +1 -``` - -#### 7. BOM, CRLF и последняя строка без перевода - >>>>> lang=zh +结果: + ```ktav a: [ (( @@ -79,9 +79,3 @@ assert($updated === $source); 结果: -```ktav -n : +1 -``` - -#### 7. BOM、CRLF 及无换行符的末行 - diff --git a/root-docs/README/editing-cookbook/body-5.md b/root-docs/README/editing-cookbook/body-5.md index 7c239c3..3808886 100644 --- a/root-docs/README/editing-cookbook/body-5.md +++ b/root-docs/README/editing-cookbook/body-5.md @@ -1,7 +1,16 @@ >>>>> lang=en +Result: + +```ktav +n : +1 +``` + +#### 7. BOM, CRLF and an unterminated final line + The returned string keeps the BOM and CRLF, and does not gain a final newline. Its escaped representation is shown to make the bytes visible. ```php +use Ktav\PureBackend; $source = "\u{FEFF}port: 8080\r\nhost: db"; $updated = PureBackend::editValue($source, "port", 9090); ``` @@ -16,20 +25,19 @@ Expansion is deterministic: a multiline replacement, growth beyond `max(100, ori #### 8. Exact Integer replacement -The source Integer domain is signed 64-bit. This value exceeds JavaScript's safe-Number range but fits i64; use an exact host representation, not a rounded floating-point value. A typed Integer outside i64 cannot be preserved as an Integer in source and is refused instead of truncated. Use a String when a large identifier is text. Float identity distinguishes negative and positive zero; Object no-op equality ignores key order, while Array order remains significant. - -```php -$updated = PureBackend::editValue("n: 1\n", "n", ['$i' => '9007199254740993']); -``` +>>>>> lang=ru +Результат: ```ktav -n: 9007199254740993 +n : +1 ``` ->>>>> lang=ru +#### 7. BOM, CRLF и последняя строка без перевода + Результат сохраняет BOM и CRLF, не добавляя финальный перевод строки. Экранированное представление делает эти байты видимыми. ```php +use Ktav\PureBackend; $source = "\u{FEFF}port: 8080\r\nhost: db"; $updated = PureBackend::editValue($source, "port", 9090); ``` @@ -44,20 +52,17 @@ $updated = PureBackend::editValue($source, "port", 9090); #### 8. Точная замена Integer -Домен Integer в исходнике — знаковый 64-битный. Это значение больше безопасного диапазона JavaScript Number, но помещается в i64; используйте точное host-представление, а не округлённое число с плавающей точкой. Типизированный Integer вне i64 невозможно сохранить в исходнике как Integer: правка отказывает, не обрезая значение. Для текстового большого идентификатора используйте String. Float различает отрицательный и положительный нуль; no-op для Object не зависит от порядка ключей, порядок Array значим. - -```php -$updated = PureBackend::editValue("n: 1\n", "n", ['$i' => '9007199254740993']); -``` - +>>>>> lang=zh ```ktav -n: 9007199254740993 +n : +1 ``` ->>>>> lang=zh +#### 7. BOM、CRLF 及无换行符的末行 + 返回值保留 BOM 和 CRLF,且不会增加末尾换行。以下转义表示使这些字节清晰可见。 ```php +use Ktav\PureBackend; $source = "\u{FEFF}port: 8080\r\nhost: db"; $updated = PureBackend::editValue($source, "port", 9090); ``` @@ -74,11 +79,3 @@ $updated = PureBackend::editValue($source, "port", 9090); 源文本的 Integer 域是有符号 64 位。此值超过 JavaScript Number 的安全整数范围,但仍在 i64 内;应使用精确的宿主表示,而非已舍入的浮点值。超出 i64 的类型化 Integer 无法在源码中保持 Integer 身份,因此会被拒绝而不是截断。大型文本标识符应使用 String。Float 区分负零和正零;Object 的 no-op 相等忽略键顺序,而 Array 顺序仍然重要。 -```php -$updated = PureBackend::editValue("n: 1\n", "n", ['$i' => '9007199254740993']); -``` - -```ktav -n: 9007199254740993 -``` - diff --git a/root-docs/README/editing-cookbook/body-6.md b/root-docs/README/editing-cookbook/body-6.md new file mode 100644 index 0000000..ba7e014 --- /dev/null +++ b/root-docs/README/editing-cookbook/body-6.md @@ -0,0 +1,82 @@ +>>>>> lang=en +The source Integer domain is signed 64-bit. This value exceeds JavaScript's safe-Number range but fits i64; use an exact host representation, not a rounded floating-point value. A typed Integer outside i64 cannot be preserved as an Integer in source and is refused instead of truncated. Use a String when a large identifier is text. Float identity distinguishes negative and positive zero; Object no-op equality ignores key order, while Array order remains significant. + +```php +$updated = PureBackend::editValue("n: 1\n", "n", ['$i' => '9007199254740993']); +``` + +```ktav +n: 9007199254740993 +``` + +#### 9. Insert, remove and rename (textual and segment paths) + +These new 0.9 insert/remove/rename operations are available through both pure and native backends and follow the same mutation contract. Insert adds a new final Object key without overwriting; removal targets an existing Object member or Array element without pruning ancestors (later Array elements shift); renaming requires an existing final Object member and a destination key absent from that same Object, preserving position and value. Insertion requires an existing parent Object; insertion into an Array is unsupported. Missing targets and invalid path/segment inputs are errors. Textual paths split on dots, with `\.` for a literal dot and `\\` for a literal backslash. Segment variants accept decoded literal path segments. `newKey` is one decoded key, not a path. Each snippet is independent. + +```php +use Ktav\PureBackend; +$source = 'settings: {old: 1, "a.b": 3}' . "\n"; +$inserted = PureBackend::insertValue($source, "settings.new", 2); +$insertedLiteral = PureBackend::insertValueSegments($source, ["settings", "added"], 2); +$removed = PureBackend::removeValue($source, "settings.old"); +$removedLiteral = PureBackend::removeValueSegments($source, ["settings", "a.b"]); +$renamed = PureBackend::renameKey($source, "settings.old", "new.name"); +$renamedLiteral = PureBackend::renameKeySegments($source, ["settings", "old"], "new.name"); +``` + +An existing insertion key is an error, not an overwrite. Array elements shift after removal. Structural edits to containers with interior comments are unsupported because comments cannot be preserved losslessly. Inline dotted syntax is supported for value replacement, but structural insert/remove/rename requiring a synthetic, noncontiguous dotted path is unsupported. A trailing comma is preserved when the edit can be represented losslessly; the editor does not prune empty ancestors or promise lossless rewriting for every structural layout. + +>>>>> lang=ru +Домен Integer в исходнике — знаковый 64-битный. Это значение больше безопасного диапазона JavaScript Number, но помещается в i64; используйте точное host-представление, а не округлённое число с плавающей точкой. Типизированный Integer вне i64 невозможно сохранить в исходнике как Integer: правка отказывает, не обрезая значение. Для текстового большого идентификатора используйте String. Float различает отрицательный и положительный нуль; no-op для Object не зависит от порядка ключей, порядок Array значим. + +```php +$updated = PureBackend::editValue("n: 1\n", "n", ['$i' => '9007199254740993']); +``` + +```ktav +n: 9007199254740993 +``` + +#### 9. Вставка, удаление и переименование (текстовые пути и сегменты) + +Новые операции вставки, удаления и переименования API 0.9 доступны через pure- и native-бэкенды и следуют одному контракту изменений. Вставка добавляет новый последний ключ Object без перезаписи; удаление удаляет существующий член Object или элемент Array, не удаляя предков (последующие элементы Array сдвигаются); переименование требует существующий последний член Object и отсутствующий целевой ключ в том же Object, сохраняя позицию и значение. Для вставки родительский путь должен вести к существующему Object; вставка в Array не поддерживается. Отсутствующие цели и некорректный ввод путей/сегментов завершаются ошибкой. Текстовый путь разделяется по точкам; `\.` задаёт буквальную точку, `\\` — буквальную обратную косую черту. Сегментные варианты принимают декодированные буквальные сегменты пути. `newKey` — один декодированный ключ, а не путь. Каждый пример независим. + +```php +use Ktav\PureBackend; +$source = 'settings: {old: 1, "a.b": 3}' . "\n"; +$inserted = PureBackend::insertValue($source, "settings.new", 2); +$insertedLiteral = PureBackend::insertValueSegments($source, ["settings", "added"], 2); +$removed = PureBackend::removeValue($source, "settings.old"); +$removedLiteral = PureBackend::removeValueSegments($source, ["settings", "a.b"]); +$renamed = PureBackend::renameKey($source, "settings.old", "new.name"); +$renamedLiteral = PureBackend::renameKeySegments($source, ["settings", "old"], "new.name"); +``` + +Вставка при существующем ключе завершается ошибкой, а не перезаписью. Элементы Array после удаления сдвигаются. Структурные изменения контейнеров с внутренними комментариями не поддерживаются, поскольку комментарии нельзя сохранить без потерь. Встроенная dotted-форма поддерживается для замены значения, но структурные вставка/удаление/переименование, требующие синтетического непоследовательного dotted-пути, не поддерживаются. Конечная запятая сохраняется, если изменение можно представить без потерь; редактор не удаляет пустых предков и не гарантирует без потерь переписывать любую структурную раскладку. + +>>>>> lang=zh +```php +$updated = PureBackend::editValue("n: 1\n", "n", ['$i' => '9007199254740993']); +``` + +```ktav +n: 9007199254740993 +``` + +#### 9. 插入、删除和重命名(文本路径和路径段) + +新的 0.9 插入、删除和重命名操作可通过 pure 和 native 后端使用,并遵循相同的修改契约。插入会添加新的最后一个 Object 键而不覆盖已有键;删除现有 Object 成员或 Array 元素但保留其祖先(后续 Array 元素会移位);重命名要求最后一个 Object 成员存在,且同一 Object 中目标键不存在,同时保留其位置和值。插入路径的父级必须指向现有 Object;不支持向 Array 插入。目标不存在或路径/路径段输入无效时会报错。文本路径按点拆分;`\.` 表示字面点,`\\` 表示字面反斜杠。路径段变体接收已解码的字面路径段。`newKey` 是单个已解码键名,而非路径。每个代码片段相互独立。 + +```php +use Ktav\PureBackend; +$source = 'settings: {old: 1, "a.b": 3}' . "\n"; +$inserted = PureBackend::insertValue($source, "settings.new", 2); +$insertedLiteral = PureBackend::insertValueSegments($source, ["settings", "added"], 2); +$removed = PureBackend::removeValue($source, "settings.old"); +$removedLiteral = PureBackend::removeValueSegments($source, ["settings", "a.b"]); +$renamed = PureBackend::renameKey($source, "settings.old", "new.name"); +$renamedLiteral = PureBackend::renameKeySegments($source, ["settings", "old"], "new.name"); +``` + +插入时若键已存在会报错,不会覆盖。删除后 Array 元素会移位。由于无法无损保留注释,不支持对内部含注释的容器进行结构编辑。行内点分语法支持值替换,但需要合成非连续点分路径的结构插入/删除/重命名不受支持。若编辑可无损表示,则保留末尾逗号;编辑器不会清除空祖先,也不保证所有结构布局都能无损重写。 + diff --git a/root-docs/README/editing-cookbook/meta.js b/root-docs/README/editing-cookbook/meta.js index f763e8e..5d4eefe 100644 --- a/root-docs/README/editing-cookbook/meta.js +++ b/root-docs/README/editing-cookbook/meta.js @@ -3,5 +3,5 @@ export default { "number": null, "level": null, "title": null, - "bodyParts": 5 + "bodyParts": 6 } diff --git a/src/Ktav.php b/src/Ktav.php index 07e6573..02a2799 100644 --- a/src/Ktav.php +++ b/src/Ktav.php @@ -169,6 +169,7 @@ public static function canonicalFromSource(string $src): string */ public static function editValue(string $source, string $path, $replacement): string { + self::validateEditSource($source); return NativeLib::callEditBytes( 'ktav_edit_value', $source, @@ -187,6 +188,7 @@ public static function editValue(string $source, string $path, $replacement): st */ public static function editValueSegments(string $source, array $segments, $replacement): string { + self::validateEditSource($source); // The segments transport is a JSON array of literal strings. // A json_encode failure is surfaced as a typed transport error // BEFORE any native call — the cause is never swallowed by a @@ -216,6 +218,71 @@ public static function editValueSegments(string $source, array $segments, $repla ); } + /** Append a new final Object key; existing keys are never overwritten. */ + public static function insertValue(string $source, string $path, $replacement): string + { + self::validateEditSource($source); + return NativeLib::callEditBytes('ktav_insert_value', $source, $path, WireJson::encodeEditReplacement($replacement)); + } + + /** Segment-path variant of {@see insertValue}. */ + public static function insertValueSegments(string $source, array $segments, $replacement): string + { + self::validateEditSource($source); + return NativeLib::callEditMutationBytes('ktav_insert_value_segments', [ + $source, self::encodeEditSegments($segments), WireJson::encodeEditReplacement($replacement), + ]); + } + + /** Remove the addressed value without pruning empty ancestors. */ + public static function removeValue(string $source, string $path): string + { + self::validateEditSource($source); + return NativeLib::callEditMutationBytes('ktav_remove_value', [$source, $path]); + } + + /** Segment-path variant of {@see removeValue}. */ + public static function removeValueSegments(string $source, array $segments): string + { + self::validateEditSource($source); + return NativeLib::callEditMutationBytes('ktav_remove_value_segments', [$source, self::encodeEditSegments($segments)]); + } + + /** Rename the final key using a literal decoded UTF-8 key. */ + public static function renameKey(string $source, string $path, string $newKey): string + { + self::validateEditSource($source); + return NativeLib::callEditMutationBytes('ktav_rename_key', [$source, $path, $newKey]); + } + + /** Segment-path variant of {@see renameKey}. */ + public static function renameKeySegments(string $source, array $segments, string $newKey): string + { + self::validateEditSource($source); + return NativeLib::callEditMutationBytes('ktav_rename_key_segments', [$source, self::encodeEditSegments($segments), $newKey]); + } + + private static function validateEditSource(string $source): void + { + // Parse with the native implementation before preparing mutation + // transport, so parser errors take precedence without rewriting source. + NativeLib::callBytes('ktav_loads', $source); + } + + private static function encodeEditSegments(array $segments): string + { + $json = json_encode(array_values($segments), JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE); + if ($json === false) { + throw KtavException::fromEnvelope([ + 'error' => 'Message', 'reason' => null, 'line' => null, 'line_text' => null, + 'span' => null, 'path' => null, 'canonical' => null, 'spec_section' => null, + 'body' => null, 'message' => 'edit segments transport is not JSON-encodable: ' . json_last_error_msg(), + ]); + } + return $json; + } + + /** * Version string reported by the loaded `ktav_cabi`. With the * immutable git-core pin the string is informational; the diff --git a/src/NativeLib.php b/src/NativeLib.php index fbb9340..4739b67 100644 --- a/src/NativeLib.php +++ b/src/NativeLib.php @@ -5,10 +5,9 @@ namespace Ktav; /** - * FFI binding to the `ktav_cabi` shared library. Nine functions, all - * using the canonical "caller-owned input pointer, callee-owned output - * buffer" pattern. The output buffer is freed via `ktav_free` after - * the PHP side has copied the bytes out. + * FFI binding to the `ktav_cabi` shared library. Document functions and + * source-edit/mutation functions use caller-owned input pointers and + * callee-owned output buffers. Returned buffers are freed via `ktav_free`. * * Internal — do not import directly. Use the {@see Ktav} facade. */ @@ -84,11 +83,11 @@ private static function ffi(): \FFI ); } // Provenance: a stale override / cache entry may carry an OLD - // binary. Since the immutable git-core pin (447a00b) the + // binary. Since the immutable git-core pin (8b6b45f) the // version STRING is no longer statically knowable, so the // AUTHORITATIVE load gate is the C ABI version: an ABI-1 (or // any non-2) binary is rejected for EVERY native operation. - // The exact 447a00b rev is provenance-checked in CI against + // The exact 8b6b45f rev is provenance-checked in CI against // Cargo.lock instead of here. self::assertAbiVersion((int) self::$ffi->ktav_abi_version(), $path); return self::$ffi; @@ -96,7 +95,7 @@ private static function ffi(): \FFI /** * Shared ABI gate: since the user-approved ABI 1 -> 2 bump, EVERY - * native call (original nine AND source edit) is served only by a + * native call (document functions and mutation operations) is served only by a * binary reporting ktav_abi_version() == 2; an ABI-1 binary is * rejected at load time with a clear version error — never a * silent pure fallback. Static so the rejection mechanism itself @@ -109,7 +108,7 @@ public static function assertAbiVersion(int $actual, string $path = 'ktav_cabi') 'ktav_cabi ABI version mismatch in ' . $path . ': expected ' . self::EXPECTED_ABI_VERSION . ', got ' . $actual . ' — the loaded binary predates the user-approved ABI-2' - . ' source-edit set; pin the matching native library' + . ' mutation set; pin the matching native library' ); } } @@ -137,12 +136,64 @@ public static function assertAbiVersion(int $actual, string $path = 'ktav_cabi') const uint8_t *replacement, size_t replacement_len, uint8_t **out_buf, size_t *out_len, char **out_err, size_t *out_err_len); - int ktav_abi_version(); + void ktav_free(uint8_t *ptr, size_t len); + C; + private const MUTATION_CDEF = <<<'C' + int ktav_insert_value( + const uint8_t *src, size_t src_len, const uint8_t *path, size_t path_len, + const uint8_t *replacement, size_t replacement_len, + uint8_t **out_buf, size_t *out_len, char **out_err, size_t *out_err_len); + int ktav_insert_value_segments( + const uint8_t *src, size_t src_len, const uint8_t *path, size_t path_len, + const uint8_t *replacement, size_t replacement_len, + uint8_t **out_buf, size_t *out_len, char **out_err, size_t *out_err_len); + int ktav_remove_value( + const uint8_t *src, size_t src_len, const uint8_t *path, size_t path_len, + uint8_t **out_buf, size_t *out_len, char **out_err, size_t *out_err_len); + int ktav_remove_value_segments( + const uint8_t *src, size_t src_len, const uint8_t *path, size_t path_len, + uint8_t **out_buf, size_t *out_len, char **out_err, size_t *out_err_len); + int ktav_rename_key( + const uint8_t *src, size_t src_len, const uint8_t *path, size_t path_len, + const uint8_t *new_key, size_t new_key_len, + uint8_t **out_buf, size_t *out_len, char **out_err, size_t *out_err_len); + int ktav_rename_key_segments( + const uint8_t *src, size_t src_len, const uint8_t *path, size_t path_len, + const uint8_t *new_key, size_t new_key_len, + uint8_t **out_buf, size_t *out_len, char **out_err, size_t *out_err_len); + int ktav_abi_version(); void ktav_free(uint8_t *ptr, size_t len); C; + private static ?\FFI $mutationFfi = null; + + private static function mutationFfi(): \FFI + { + if (self::$mutationFfi !== null) { + return self::$mutationFfi; + } + if (!extension_loaded('ffi')) { + throw new KtavException('PHP FFI extension is required (php.ini: ffi.enable=1).'); + } + $path = NativeLoader::resolve(); + try { + self::$mutationFfi = \FFI::cdef(self::MUTATION_CDEF, $path); + } catch (\FFI\Exception $e) { + throw new KtavException( + 'ktav insert/remove/rename symbols are not available in ' . $path + . ' — the loaded ktav_cabi does not export the ABI-' + . self::EXPECTED_ABI_VERSION . ' mutation set. Pin a matching native library.' + . ' Detail: ' . $e->getMessage(), + 0, + $e, + ); + } + self::assertAbiVersion((int) self::$mutationFfi->ktav_abi_version(), $path); + return self::$mutationFfi; + } + private static ?\FFI $editFfi = null; /** @@ -175,7 +226,7 @@ private static function editFfi(): \FFI throw new KtavException( 'ktav_edit_value / ktav_edit_value_segments are not available in ' . $path . ' — the loaded ktav_cabi does not export the ABI-' - . self::EXPECTED_ABI_VERSION . ' source-edit set.' + . self::EXPECTED_ABI_VERSION . ' source-edit/mutation set.' . ' Pin the native library that exports these symbols; no pure fallback is performed.' . ' Detail: ' . $e->getMessage(), 0, @@ -197,9 +248,24 @@ private static function editFfi(): \FFI */ public static function callEditBytes(string $fn, string $src, string $path, string $replacement): string { - $ffi = self::editFfi(); - $lens = [strlen($src), strlen($path), strlen($replacement)]; - $inputs = [$src, $path, $replacement]; + return self::callEditMutationBytes($fn, [$src, $path, $replacement]); + } + + /** Call any mutation export using its ordered UTF-8 byte input buffers. */ + public static function callEditMutationBytes(string $fn, array $inputs): string + { + if (!in_array($fn, [ + 'ktav_edit_value', 'ktav_edit_value_segments', + 'ktav_insert_value', 'ktav_insert_value_segments', + 'ktav_remove_value', 'ktav_remove_value_segments', + 'ktav_rename_key', 'ktav_rename_key_segments', + ], true)) { + throw new KtavException('unsupported native edit operation: ' . $fn); + } + $ffi = in_array($fn, ['ktav_edit_value', 'ktav_edit_value_segments'], true) + ? self::editFfi() + : self::mutationFfi(); + $lens = array_map('strlen', $inputs); // One live byte per input (see callBytes for the NULL-with-len-0 // rationale); the pad byte is never read. @@ -219,15 +285,16 @@ public static function callEditBytes(string $fn, string $src, string $path, stri $outErrLen = $ffi->new('size_t'); try { - $rc = $ffi->{$fn}( - $buffers[0], $lens[0], - $buffers[1], $lens[1], - $buffers[2], $lens[2], - \FFI::addr($outBuf), - \FFI::addr($outLen), - \FFI::addr($outErr), - \FFI::addr($outErrLen), - ); + $args = []; + foreach ($buffers as $i => $buffer) { + $args[] = $buffer; + $args[] = $lens[$i]; + } + $args[] = \FFI::addr($outBuf); + $args[] = \FFI::addr($outLen); + $args[] = \FFI::addr($outErr); + $args[] = \FFI::addr($outErrLen); + $rc = $ffi->{$fn}(...$args); if ($rc !== 0) { // Free through the SAME FFI instance that produced the // pointers: CData types are per-instance, and the base @@ -264,9 +331,12 @@ private static function copyAndFreeEdit(\FFI $ffi, $ptr, int $len): string if ($len <= 0 || $ptr === null) { return ''; } - $bytes = \FFI::string($ptr, $len); - $ffi->ktav_free($ffi->cast('uint8_t*', $ptr), $len); - return $bytes !== false ? $bytes : ''; + try { + $bytes = \FFI::string($ptr, $len); + return $bytes !== false ? $bytes : ''; + } finally { + $ffi->ktav_free($ffi->cast('uint8_t*', $ptr), $len); + } } /** freeIfPresent counterpart bound to the EDIT FFI instance. */ @@ -391,9 +461,12 @@ private static function copyAndFree($ptrField, int $len): string if ($ptr === null) { return ''; } - $bytes = \FFI::string($ptr, $len); - self::ffi()->ktav_free($ptr, $len); - return $bytes !== false ? $bytes : ''; + try { + $bytes = \FFI::string($ptr, $len); + return $bytes !== false ? $bytes : ''; + } finally { + self::ffi()->ktav_free($ptr, $len); + } } /** @param \FFI\CData $ptrField */ diff --git a/src/Pure/Edit/EditEnvelope.php b/src/Pure/Edit/EditEnvelope.php index 70d4895..c6b50dc 100644 --- a/src/Pure/Edit/EditEnvelope.php +++ b/src/Pure/Edit/EditEnvelope.php @@ -50,6 +50,16 @@ public static function notFound(): KtavException ); } + /** EditAlreadyExists — insertion never overwrites an Object member. */ + public static function alreadyExists(): KtavException + { + return self::envelope( + 'EditAlreadyExists', + null, + 'edit target already exists; insertion never overwrites' + ); + } + /** EditUnsupported with the human-readable limitation text. */ public static function unsupported(string $reason): KtavException { @@ -68,7 +78,7 @@ public static function unsupported(string $reason): KtavException */ public static function message(string $text): KtavException { - return self::envelope('Message', null, $text); + return self::envelope('Message', $text, $text); } private static function envelope(string $code, ?string $body, string $message): KtavException diff --git a/src/Pure/Edit/EditSplice.php b/src/Pure/Edit/EditSplice.php index bbc5ad6..4ca5a13 100644 --- a/src/Pure/Edit/EditSplice.php +++ b/src/Pure/Edit/EditSplice.php @@ -6,6 +6,7 @@ use Ktav\KtavException; use Ktav\Pure\PureFloat; +use Ktav\Pure\PureInlineScan; use Ktav\Pure\PureParser; use Ktav\Pure\PureScanner; use Ktav\Pure\PureText; @@ -62,7 +63,7 @@ static function () use ($path): array { if (PureScanner::validateUtf8($path) !== null) { // Transport decode failure: the path argument is // not valid UTF-8 (source-less Message envelope). - throw EditEnvelope::message('edit path is not valid UTF-8'); + throw EditEnvelope::message('path is not valid UTF-8: ' . self::utf8Error($path)); } return self::parsePath($path); }, @@ -104,6 +105,739 @@ static function () use ($segments): array { ); } + /** Remove an existing value while preserving untouched source bytes. */ + public static function removeValue(string $src, string $path): string + { + PureParser::parse($src, false); + if (PureScanner::validateUtf8($path) !== null) { + throw EditEnvelope::message('path is not valid UTF-8: ' . self::utf8Error($path)); + } + return self::removeValueSegments($src, self::parsePath($path)); + } + + /** @param string[] $segments */ + public static function removeValueSegments(string $src, array $segments): string + { + $original = EditEnvelope::toCval(PureParser::parse($src, false)); + self::validateMutationSegments($segments); + $target = self::lookupValue($original, $segments); + if ($target === null) { throw EditEnvelope::notFound(); } + list($root,) = EditTree::build($src); + $node = self::nodeAt($root, $segments); + list($from, $to, $strippedLead) = self::mutationRange($src, $root, $segments, $node); + if ($node['kind'] !== 'scalar') { + $skip = []; + self::collectMultilineScalarRanges($node, $skip); + if (self::hasCommentLine($src, $from, $to, $skip)) { + throw EditEnvelope::unsupported('target contains comment lines; removal cannot preserve them losslessly'); + } + } + $expected = $original; + if (self::removeCvalTarget($expected, $segments) === null) { throw EditEnvelope::notFound(); } + $parents = array_slice($segments, 0, -1); + $materialized = null; + if ($parents !== []) { + $emptiedFrom = null; + for ($start = 0; $start < count($parents); ++$start) { + $allEmpty = true; + for ($k = $start; $k < count($parents); ++$k) { + $ancestor = self::lookupValue($expected, array_slice($parents, 0, $k + 1)); + if ($ancestor === null || $ancestor['t'] !== 'object' || $ancestor['pairs'] !== []) { $allEmpty = false; break; } + } + if ($allEmpty) { $emptiedFrom = $start; break; } + } + if ($emptiedFrom !== null) { + $synthetic = self::nodeAt($root, array_slice($parents, 0, $emptiedFrom + 1))['slot'] === null; + $containerDepth = 0; + for ($i = 0; $i < count($parents); ++$i) { + if (self::nodeAt($root, array_slice($parents, 0, $i + 1))['slot'] !== null) { $containerDepth = $i + 1; } + } + if ($synthetic && $emptiedFrom >= $containerDepth) { + $leadLen = $strippedLead ? (substr($src, $from, 2) === "\r\n" ? 2 : 1) : 0; + $lineStart = $from + $leadLen; + $indentEnd = $lineStart; + while ($indentEnd < strlen($src) && ($wsLen = PureScanner::wsLenAt($src, $indentEnd, strlen($src), false)) > 0) { $indentEnd += $wsLen; } + $indent = substr($src, $lineStart, $indentEnd - $lineStart); + $key = implode('.', array_map([self::class, 'escapedKeySegment'], array_slice($parents, $containerDepth))); + $materialized = substr($src, $from, $leadLen) . $indent . $key . ': {}'; + if ($to > $from && ($src[$to - 1] === "\n" || $src[$to - 1] === "\r")) { + $eolStart = $src[$to - 1] === "\n" && $to >= 2 && $src[$to - 2] === "\r" ? $to - 2 : $to - 1; + $materialized .= substr($src, $eolStart, $to - $eolStart); + } + } + } + } + $cut = static function (?string $replacement) use ($src, $from, $to): string { + return substr($src, 0, $from) . ($replacement ?? '') . substr($src, $to); + }; + $candidate = $cut(null); + try { + $actual = EditEnvelope::toCval(PureParser::parse($candidate, false)); + if (EditEnvelope::cvalEqual($actual, $expected)) { return $candidate; } + } catch (KtavException $ignored) { + // A plain cut can be unparseable when it prunes a synthetic dotted ancestor. + } + $candidate = $cut($materialized); + try { + $actual = EditEnvelope::toCval(PureParser::parse($candidate, false)); + } catch (KtavException $ignored) { + throw EditEnvelope::unsupported('candidate source does not parse; no lossless edit produced'); + } + if (!EditEnvelope::cvalEqual($actual, $expected)) { + throw EditEnvelope::unsupported('semantic mismatch after splice; no lossless edit produced'); + } + return $candidate; + } + + /** Rename an existing Object member key without moving its value. */ + public static function renameKey(string $src, string $path, string $newKey): string + { + PureParser::parse($src, false); + if (PureScanner::validateUtf8($path) !== null) { throw EditEnvelope::message('path is not valid UTF-8: ' . self::utf8Error($path)); } + return self::renameKeySegments($src, self::parsePath($path), $newKey); + } + + /** @param string[] $segments */ + public static function renameKeySegments(string $src, array $segments, string $newKey): string + { + $original = EditEnvelope::toCval(PureParser::parse($src, false)); + self::validateMutationSegments($segments); + if (PureScanner::validateUtf8($newKey) !== null) { throw EditEnvelope::message('new key is not valid UTF-8: ' . self::utf8Error($newKey)); } + if ($newKey === '') { throw EditEnvelope::unsupported('empty key name is not representable'); } + $last = $segments[count($segments)-1]; + $parentPath = array_slice($segments, 0, -1); + $parent = self::lookupValue($original, $parentPath); + if ($parent === null) { throw EditEnvelope::notFound(); } + if ($parent['t'] === 'array') { + throw EditEnvelope::unsupported('rename of an Array element is not supported; only Object keys can be renamed'); + } + if ($parent['t'] !== 'object') { throw EditEnvelope::notFound(); } + if (self::cvalChild($parent, $last) === null) { throw EditEnvelope::notFound(); } + if ($last === $newKey) { return $src; } + if (self::cvalChild($parent, $newKey) !== null) { throw EditEnvelope::alreadyExists(); } + list($root,) = EditTree::build($src); + $parentNode = self::nodeAt($root, $parentPath); + $targetNode = self::nodeAt($parentNode, [$last]); + $colon = null; + if ($targetNode['slot'] !== null) { + if (isset($targetNode['slot']['colon'])) { + $colon = $targetNode['slot']['colon']; + } elseif (($targetNode['slot']['r'] ?? null) === 'block' + && isset($targetNode['slot']['anchor'])) { + $colon = $targetNode['slot']['anchor']; + } + } + if ($colon === null) { + throw EditEnvelope::unsupported('target is a noncontiguous value (dotted-key/reopen intermediate); no lossless rename range exists'); + } + list($ks, $ke) = self::mutationKeyRange($src, $colon); + $encoded = self::escapedKeySegment($newKey); + $candidate = substr($src, 0, $ks) . $encoded . substr($src, $ke); + $expected = self::renameCval($original, $segments, $newKey); + try { + $actual = EditEnvelope::toCval(PureParser::parse($candidate, false)); + } catch (KtavException $ignored) { + throw EditEnvelope::unsupported('candidate source does not parse; no lossless edit produced'); + } + if (!EditEnvelope::cvalEqual($actual, $expected)) { throw EditEnvelope::unsupported('semantic mismatch after splice; no lossless edit produced'); } + return $candidate; + } + + private static function utf8Error(string $value): string + { + $span = PureScanner::validateUtf8($value); + $start = $span[0]; + $end = $span[1]; + $length = $end - $start; + $first = ord($value[$start]); + + // Rust's Utf8Error reports error_len as the number of bytes up to + // (but not including) the first byte that cannot continue the + // sequence. Only a genuinely truncated, still-valid prefix at EOF + // has error_len == None. Constrained second-byte failures (e.g. + // E0 80) are invalid immediately, even when EOF follows. + $expected = $first >= 0xC2 && $first <= 0xDF ? 2 + : ($first >= 0xE0 && $first <= 0xEF ? 3 + : ($first >= 0xF0 && $first <= 0xF4 ? 4 : 1)); + if ($expected === 1) { + // Illegal lead bytes are their own error, regardless of any + // continuation bytes that the scanner groups into its span. + $length = 1; + } elseif ($expected > 1) { + $validPrefix = 1; + while ($validPrefix < $expected && $start + $validPrefix < strlen($value)) { + $byte = ord($value[$start + $validPrefix]); + $position = $validPrefix; + $valid = $byte >= 0x80 && $byte <= 0xBF; + if ($position === 1 && $first === 0xE0) { $valid = $byte >= 0xA0 && $byte <= 0xBF; } + elseif ($position === 1 && $first === 0xED) { $valid = $byte >= 0x80 && $byte <= 0x9F; } + elseif ($position === 1 && $first === 0xF0) { $valid = $byte >= 0x90 && $byte <= 0xBF; } + elseif ($position === 1 && $first === 0xF4) { $valid = $byte >= 0x80 && $byte <= 0x8F; } + if (!$valid) { break; } + ++$validPrefix; + } + if ($start + $validPrefix === strlen($value) && $validPrefix < $expected) { + return 'incomplete utf-8 byte sequence from index ' . $start; + } + if ($validPrefix > 1) { + $length = $validPrefix; + } elseif ($length > 1 && $first >= 0xC2 && $first <= 0xF4) { + $length = 1; + } + } + return 'invalid utf-8 sequence of ' . $length . ' bytes from index ' . $start; + } + + private static function validateMutationSegments(array $segments): void + { + if ($segments === []) { throw EditEnvelope::notFound(); } + foreach ($segments as $segment) { + if (!is_string($segment)) { throw EditEnvelope::message('edit segments transport must be a list of strings'); } + if (PureScanner::validateUtf8($segment) !== null) { throw EditEnvelope::message('edit segments transport contains invalid UTF-8'); } + } + } + + private static function removeCvalTarget(array &$value, array $segments) + { + $last = array_pop($segments); + $parent = &self::cvalAtRef($value, $segments); + if ($parent['t'] === 'object') { + foreach ($parent['pairs'] as $i => $pair) if ($pair[0] === $last) { array_splice($parent['pairs'], $i, 1); return $pair[1]; } + } elseif ($parent['t'] === 'array') { + $i = self::parseIndex($last); if (isset($parent['items'][$i])) { $v=$parent['items'][$i]; array_splice($parent['items'], $i, 1); return $v; } + } + return null; + } + + private static function &cvalAtRef(array &$value, array $segments): array + { + $cur = &$value; + foreach ($segments as $seg) { + if ($cur['t'] === 'object') { foreach ($cur['pairs'] as $i => $p) if ($p[0] === $seg) { $cur = &$cur['pairs'][$i][1]; continue 2; } } + elseif ($cur['t'] === 'array') { $i=self::parseIndex($seg); if (isset($cur['items'][$i])) { $cur = &$cur['items'][$i]; continue; } } + throw EditEnvelope::notFound(); + } + return $cur; + } + + private static function renameCval(array $value, array $segments, string $newKey): array + { + $last = array_pop($segments); + $parent = &self::cvalAtRef($value, $segments); + foreach ($parent['pairs'] as &$pair) { if ($pair[0] === $last) { $pair[0] = $newKey; break; } } + unset($pair); + return $value; + } + + private static function mutationRange(string $src, array $root, array $segments, array $node): array + { + $slot=$node['slot']; + $strippedLead = false; + if ($slot === null) { throw EditEnvelope::unsupported('target is a noncontiguous value (dotted-key/reopen intermediate); no lossless removal range exists'); } + if (!empty($node['inline'])) { + $range = self::inlineRemovalRange($src, $root, $segments, $slot); + return [$range[0], $range[1], false]; + } + $anchor=isset($slot['colon']) ? $slot['colon'] : $slot['start']; + $from=$anchor; while ($from>0 && $src[$from-1] !== "\n" && $src[$from-1] !== "\r") --$from; + if ($from === 0 && substr($src, 0, 3) === "\xEF\xBB\xBF") { $from=3; } + $to=$slot['end']; while ($to 0) { + if ($src[$from - 1] === "\n") { --$from; if ($from > 0 && $src[$from - 1] === "\r") { --$from; } $strippedLead = true; } + elseif ($src[$from - 1] === "\r") { --$from; $strippedLead = true; } + } + return [$from, $to, $strippedLead]; + } + + private static function inlineRemovalRange(string $src, array $root, array $segments, array $slot): array + { + $parents = array_slice($segments, 0, -1); + $parent = self::nodeAt($root, $parents); + $bounds = self::inlineRange($root, $parent, $parents, $src); + if ($bounds === null && $parent['kind'] === 'array' && is_array($parent['slot'])) { + $parentSlot = $parent['slot']; + $bodyStart = $parentSlot['body0'] ?? $parentSlot['start'] ?? null; + if (($parentSlot['r'] === 'pair' || $parentSlot['r'] === 'item') + && $bodyStart !== null + && $bodyStart < $parentSlot['end'] + && $src[$bodyStart] === '[' + && $src[$parentSlot['end'] - 1] === ']') { + $bounds = [$bodyStart, $parentSlot['end']]; + } + } + if ($bounds === null) { throw EditEnvelope::unsupported('internal: inline target without inline parent'); } + list($p0, $p1) = $bounds; + $body = substr($src, $p0, $p1 - $p0); + $object = $body[0] === '{'; + $scan = PureInlineScan::scan($body, $object ? 'o' : 'a', 1, strlen($body)); + if ($scan['badEscape'] !== null || $scan['closer'] === null) { throw EditEnvelope::unsupported('cannot split inline parent for removal'); } + $spans = []; + foreach ($scan['segs'] as $seg) { + list($s, $e) = PureScanner::trimBounds($body, $seg[0], $seg[1]); + if ($s < $e) { $spans[] = [$p0 + $s, $p0 + $e]; } + } + $anchor = isset($slot['colon']) ? $slot['colon'] : $slot['start']; + $pos = null; + foreach ($spans as $i => $span) { if ($span[0] <= $anchor && $anchor < $span[1]) { $pos = $i; break; } } + if ($pos === null) { throw EditEnvelope::unsupported('internal: target segment not found in inline parent'); } + if (count($spans) === 1) { return [$p0 + 1, $p1 - 1]; } + return $pos + 1 < count($spans) ? [$spans[$pos][0], $spans[$pos + 1][0]] : [$spans[$pos - 1][1], $spans[$pos][1]]; + } + + private static function mutationKeyRange(string $src, int $colon): array + { + $end = $colon; + while ($end > 0) { + $wsStart = max(0, $end - 3); + $wsLen = 0; + for ($k = $wsStart; $k < $end; ++$k) { + $len = PureScanner::wsLenAt($src, $k, $end, false); + if ($len > 0 && $k + $len === $end) { $wsLen = $len; break; } + } + if ($wsLen === 0) { break; } + $end -= $wsLen; + } + $start = $colon; + while ($start > 0 && $src[$start - 1] !== "\n" && $src[$start - 1] !== "\r") { --$start; } + if ($start === 0 && substr($src, 0, 3) === "\xEF\xBB\xBF") { $start = 3; } + $bytes = $src; + $boundary = $start; + $i = $start; + $segStart = true; + while ($i < $colon) { + if ($segStart) { + while ($i < $colon && ($wsLen = PureScanner::wsLenAt($bytes, $i, $colon, true)) > 0) { $i += $wsLen; } + if ($i < $colon && ($bytes[$i] === '"' || $bytes[$i] === "'" || $bytes[$i] === '`')) { + $quote = $bytes[$i++]; + while ($i < $colon) { + if ($bytes[$i] === '\\') { $i += 2; continue; } + if ($bytes[$i++] === $quote) { break; } + } + $segStart = false; + continue; + } + $segStart = false; + } + if ($bytes[$i] === '\\') { $i += 2; continue; } + if ($bytes[$i] === '.') { $segStart = true; $boundary = $i + 1; } + elseif ($bytes[$i] === ',' || $bytes[$i] === '{' || $bytes[$i] === '[') { $boundary = $i + 1; $segStart = true; } + ++$i; + } + while ($boundary < $end && ($wsLen = PureScanner::wsLenAt($bytes, $boundary, $end, true)) > 0) { $boundary += $wsLen; } + return [$boundary, $end]; + } + + /** Insert a new final Object key without ever overwriting. */ + public static function insertValue(string $src, string $path, $replacement): string + { + // Source parse precedes path UTF-8/path grammar diagnostics. + PureParser::parse($src, false); + if (PureScanner::validateUtf8($path) !== null) { + throw EditEnvelope::message('path is not valid UTF-8: ' . self::utf8Error($path)); + } + return self::insertValueSegments($src, self::parsePath($path), $replacement); + } + + /** @param string[] $segments */ + public static function insertValueSegments(string $src, array $segments, $replacement): string + { + $original = EditEnvelope::toCval(PureParser::parse($src, false)); + if ($segments === []) { + throw EditEnvelope::notFound(); + } + foreach ($segments as $segment) { + if (!is_string($segment)) { + throw EditEnvelope::message('edit segments transport must be a list of strings'); + } + if (PureScanner::validateUtf8($segment) !== null) { + throw EditEnvelope::message('edit segments transport contains invalid UTF-8'); + } + } + $c = self::publicToCval($replacement); + $parentSegments = array_slice($segments, 0, -1); + $key = $segments[count($segments) - 1]; + $parent = self::lookupValue($original, $parentSegments); + if ($parent === null) { + throw EditEnvelope::notFound(); + } + if ($parent['t'] === 'array') { + throw EditEnvelope::unsupported('insertion into an Array is not supported; only Object members can be created'); + } + if ($parent['t'] !== 'object') { + throw EditEnvelope::notFound(); + } + if (self::cvalChild($parent, $key) !== null) { + throw EditEnvelope::alreadyExists(); + } + return self::insertSplice($src, $original, $parentSegments, $key, $c); + } + + /** @param string[] $parentSegments */ + private static function insertSplice(string $src, $original, array $parentSegments, string $key, array $c): string + { + list($positionRoot, $rootExplicit) = EditTree::build($src); + $parentNode = self::nodeAt($positionRoot, $parentSegments); + $inlineRange = self::inlineRange($positionRoot, $parentNode, $parentSegments, $src); + if ($inlineRange !== null) { + list($from, $to) = $inlineRange; + $inner = substr($src, $from + 1, $to - $from - 2); + if ($inner === false) { + throw EditEnvelope::unsupported('internal: invalid inline parent range'); + } + $pair = self::insertInlinePairText($key, $c); + $forceLayout = (EditEnvelope::requiresBlock($c) || ( + $c['t'] === 'string' + && (strpos($c['v'], "\n") !== false || strpos($c['v'], "\r") !== false + || PureText::stringNeedsMultiline($c['v'])) + )) && self::blockEncodable($c); + if (PureScanner::trimBounds($inner, 0, strlen($inner))[0] === PureScanner::trimBounds($inner, 0, strlen($inner))[1]) { + $spliceFrom = $from + 1; + $spliceTo = $to - 1; + $insert = $pair; + $candidate = substr($src, 0, $spliceFrom) . $insert . substr($src, $spliceTo); + } else { + // Insert immediately before the closer; preserve whitespace + // preceding the closer and account for comma/space in range. + $spliceFrom = $to - 1; + $spliceTo = $spliceFrom; + $inlineText = '{' . $inner . '}'; + $inlineScan = PureInlineScan::scan($inlineText, 'o', 1, strlen($inlineText)); + if ($inlineScan['badEscape'] !== null || $inlineScan['closer'] === null) { + throw EditEnvelope::unsupported('cannot split inline parent for insertion'); + } + // Insert after a structural trailing comma, before trailing whitespace. + $lastSegment = $inlineScan['segs'][count($inlineScan['segs']) - 1]; + list($lastStart, $lastEnd) = PureScanner::trimBounds( + $inlineText, + $lastSegment[0], + $lastSegment[1] + ); + $hasTrailingComma = count($inlineScan['segs']) > 1 + && $lastStart === $lastEnd; + if ($hasTrailingComma) { + $comma = $inlineScan['segs'][count($inlineScan['segs']) - 2][1]; + $spliceFrom = $from + $comma + 1; + $spliceTo = $spliceFrom; + $insert = ' ' . $pair . ','; + } else { + $insert = ', ' . $pair; + } + $candidate = substr($src, 0, $spliceFrom) . $insert . substr($src, $spliceTo); + } + $candidate = self::layoutInsertCandidate( + $src, + $candidate, + $positionRoot, + $parentSegments, + $c, + $spliceFrom, + $spliceTo, + strlen($insert), + true, + $forceLayout + ); + return self::verifyInsertion($candidate, $original, $parentSegments, $key, $c); + } + if ($parentSegments !== []) { + // A block Object has a positional Block slot whose start/end + // delimit the opener through the closing brace. Insert before + // the closer, using the last sibling's indentation (or one + // level below the opener for an empty Object). + if ($parentNode['kind'] !== 'object') { + throw EditEnvelope::unsupported('internal: parent node is not an object'); + } + $slot = $parentNode['slot']; + if (!is_array($slot) || $slot['r'] !== 'block') { + throw EditEnvelope::unsupported('parent is a noncontiguous value (dotted-key/reopen intermediate); no lossless insertion point exists'); + } + $openerIndent = EditTree::lineIndent($src, $slot['start']); + $childIndent = $openerIndent . ' '; + if ($parentNode['pairs'] !== []) { + $last = $parentNode['pairs'][count($parentNode['pairs']) - 1][1]; + if (is_array($last['slot'])) { + $lastPos = $last['slot']['r'] === 'pair' ? $last['slot']['colon'] : $last['slot']['start']; + $childIndent = EditTree::lineIndent($src, $lastPos); + } + } + $at = self::physicalLineRange($src, $slot['end'])[0]; + $eol = EditTree::detectEol($src, $slot['end']); + $pair = self::insertBlockPair($key, $c, $childIndent, $eol); + $candidate = substr($src, 0, $at) . $childIndent . $pair . $eol . substr($src, $at); + $candidate = self::layoutInsertCandidate($src, $candidate, $positionRoot, $parentSegments, $c, $at, $at, strlen($childIndent . $pair . $eol), false); + return self::verifyInsertion($candidate, $original, $parentSegments, $key, $c); + } + if ($rootExplicit) { + $closer = self::rootCloserLineStart($src); + if ($closer === null) { + throw EditEnvelope::unsupported('internal: explicit root without closer'); + } + $childIndent = $positionRoot['pairs'] === [] ? ' ' : ''; + if ($positionRoot['pairs'] !== []) { + $last = $positionRoot['pairs'][count($positionRoot['pairs']) - 1][1]; + if (is_array($last['slot'])) { + $lastPos = $last['slot']['r'] === 'pair' ? $last['slot']['colon'] : $last['slot']['start']; + $childIndent = EditTree::lineIndent($src, $lastPos); + } + } + $eol = EditTree::detectEol($src, $closer); + $pair = self::insertBlockPair($key, $c, $childIndent, $eol); + $candidate = substr($src, 0, $closer) . $childIndent . $pair . $eol . substr($src, $closer); + $candidate = self::layoutInsertCandidate($src, $candidate, $positionRoot, [], $c, $closer, $closer, strlen($childIndent . $pair . $eol), false); + return self::verifyInsertion($candidate, $original, [], $key, $c); + } + if ($positionRoot['inline']) { + throw EditEnvelope::unsupported('pure root insertion requires an Object'); + } + if ($original['t'] !== 'object') { + throw EditEnvelope::unsupported('insertion parent is not an Object'); + } + $eol = self::detectEol($src, strlen($src)); + $pair = self::insertBlockPair($key, $c, '', $eol); + $endsWithEol = $src !== '' && ($src[strlen($src) - 1] === "\n" || $src[strlen($src) - 1] === "\r"); + if ($src === '') { + $insert = $pair; + } elseif ($endsWithEol) { + $insert = $pair . $eol; + } else { + $insert = $eol . $pair; + } + $candidate = $src . $insert; + $candidate = self::layoutInsertCandidate($src, $candidate, $positionRoot, [], $c, strlen($src), strlen($src), strlen($insert), false); + return self::verifyInsertion($candidate, $original, [], $key, $c); + } + + /** + * Render a new pair in a block slot using the same value planner as + * replacement. Compound values use block rendering; strings retain the + * planner's raw-marker/multiline decisions and source EOL/indent. + */ + private static function insertBlockPair(string $key, array $c, string $indent, string $eol): string + { + if ($key === '') { + throw EditEnvelope::unsupported('empty key name is not representable'); + } + list($body, $raw) = self::planValue( + $c, + 'pair', + false, + false, + $indent, + $eol, + false, + true + ); + return self::escapedKeySegment($key) . ':' . ($raw ? ':' : '') . ' ' . $body; + } + + private static function nodeAt(array $root, array $segments): array + { + $node = $root; + foreach ($segments as $segment) { + if ($node['kind'] === 'object') { + $node = self::childOf($node, $segment); + } elseif ($node['kind'] === 'array') { + $idx = self::parseIndex($segment); + $node = $node['items'][$idx] ?? null; + } else { + $node = null; + } + if ($node === null) { + throw EditEnvelope::notFound(); + } + } + return $node; + } + + private static function inlineRange(array $root, array $node, array $path, string $src): ?array + { + if (isset($node['slot']) && is_array($node['slot'])) { + $slot = $node['slot']; + if ($slot['r'] !== 'pair' && $slot['r'] !== 'item') { + return null; + } + if (isset($slot['body0']) && $src[$slot['body0']] === '{') { + $start = $slot['body0']; + $end = $slot['end']; + if ($start < $end && $src[$end - 1] === '}') { + return [$start, $end]; + } + } + if (isset($slot['colon'])) { + $start = $slot['start']; + $end = $slot['end']; + if ($start < $end && $src[$start] === '{' && $src[$end - 1] === '}') { + return [$start, $end]; + } + } + } + if ($path === [] && !empty($root['inline'])) { + $metadata = $root['rootRange'] ?? null; + if (is_array($metadata)) { + $start = $metadata['start'] ?? null; + $end = $metadata['end'] ?? null; + if (is_int($start) && is_int($end) && $start < $end + && (($src[$start] === '{' && $src[$end - 1] === '}') + || ($src[$start] === '[' && $src[$end - 1] === ']'))) { + return [$start, $end]; + } + } + } + return null; + } + + /** Locate the explicit root Object's closing-brace line. */ + private static function rootCloserLineStart(string $src): ?int + { + $end = strlen($src); + while ($end > 0) { + // Skip a terminal EOL before locating the preceding content + // line; using the LF byte itself would return the same line + // start forever. + if ($src[$end - 1] === "\n") { + --$end; + if ($end > 0 && $src[$end - 1] === "\r") { --$end; } + continue; + } + if ($src[$end - 1] === "\r") { + --$end; + continue; + } + list($start, $lineEnd) = self::physicalLineRange($src, $end - 1); + list($ts, $te) = PureScanner::trimBounds($src, $start, $lineEnd); + if (substr($src, $ts, $te - $ts) === '}') { + return $start; + } + $end = $start; + } + return null; + } + + /** @return int[] */ + private static function physicalLineRange(string $src, int $pos): array + { + $start = $pos; + while ($start > 0 && $src[$start - 1] !== "\n" && $src[$start - 1] !== "\r") { --$start; } + $end = $pos; + $len = strlen($src); + while ($end < $len && $src[$end] !== "\n" && $src[$end] !== "\r") { ++$end; } + return [$start, $end]; + } + + private static function blockEncodable(array $c): bool + { + if ($c['t'] === 'string') { + if (strpos($c['v'], "\r") !== false) { + return false; + } + foreach (explode("\n", $c['v']) as $line) { + if (trim($line, " \t") === '))') { + return false; + } + } + return true; + } + if ($c['t'] === 'object') { + foreach ($c['pairs'] as $pair) { + if (!self::blockEncodable($pair[1])) { return false; } + } + } elseif ($c['t'] === 'array') { + foreach ($c['items'] as $item) { + if (!self::blockEncodable($item)) { return false; } + } + } + return true; + } + + private static function insertInlinePairText(string $key, array $c): string + { + if ($key === '') { + throw EditEnvelope::unsupported('empty key name is not representable'); + } + $body = $c['t'] === 'string' + ? EditEnvelope::encodeInline($c['v'], PureText::needsRawMarker($c['v'])) + : self::inlineBody($c, true); + return self::escapedKeySegment($key) . ': ' . $body; + } + + private static function verifyInsertion(string $candidate, $original, array $parentSegments, string $key, array $c): string + { + try { + $patched = EditEnvelope::toCval(PureParser::parse($candidate, false)); + } catch (KtavException $e) { + throw EditEnvelope::unsupported('patch produced an invalid document: ' . $e->getMessage()); + } + $expected = $original; + $parents = &$expected; + foreach ($parentSegments as $segment) { + if (!is_array($parents)) { + throw EditEnvelope::notFound(); + } + if (($parents['t'] ?? null) === 'object') { + $idx = null; + foreach ($parents['pairs'] as $i => $pair) { + if ($pair[0] === $segment) { $idx = $i; break; } + } + if ($idx === null) { throw EditEnvelope::notFound(); } + $parents = &$parents['pairs'][$idx][1]; + } elseif (($parents['t'] ?? null) === 'array') { + $idx = self::parseIndex($segment); + if (!array_key_exists($idx, $parents['items'])) { throw EditEnvelope::notFound(); } + $parents = &$parents['items'][$idx]; + } else { + throw EditEnvelope::notFound(); + } + } + if (!is_array($parents) || ($parents['t'] ?? null) !== 'object') { + throw EditEnvelope::notFound(); + } + $parents['pairs'][] = [$key, $c]; + unset($parents); + if (!EditEnvelope::cvalEqual($patched, $expected)) { + throw EditEnvelope::unsupported('semantic mismatch after splice; no lossless patch produced'); + } + return $candidate; + } + + /** Encode a root-level pair with the pure inline/compound renderer. */ + private static function insertRootPair(string $key, array $c): string + { + $keyText = self::escapedKeySegment($key); + if ($c['t'] === 'string' && $c['v'] === '') { + $body = '()'; + } elseif ($c['t'] === 'object' || $c['t'] === 'array') { + $body = self::inlineBody($c, true); + } elseif ($c['t'] === 'string') { + $body = EditEnvelope::encodeInline($c['v'], PureText::needsRawMarker($c['v'])); + } else { + $body = self::scalarBodyText($c); + } + return $keyText . ': ' . $body; + } + + /** Source EOL policy shared with existing edit planners. */ + private static function detectEol(string $text, int $at): string + { + for ($i = max(0, $at); $i < strlen($text); ++$i) { + if ($text[$i] === "\n") { + return "\n"; + } + if ($text[$i] === "\r") { + return isset($text[$i + 1]) && $text[$i + 1] === "\n" ? "\r\n" : "\r"; + } + } + $prefix = substr($text, 0, max(0, $at)); + $cr = strrpos($prefix, "\r"); + $lf = strrpos($prefix, "\n"); + if ($cr !== false && ($lf === false || $cr > $lf)) { + return "\r"; + } + if ($lf !== false && $lf > 0 && $prefix[$lf - 1] === "\r") { + return "\r\n"; + } + return "\n"; + } + /** * Textual path grammar: '.' separates; `\.` and `\\` are literals; * any other escape or a trailing lone backslash, an empty path and @@ -1368,7 +2102,8 @@ private static function layoutAdjust( int $from, int $to, int $inserted, - bool $inlineLeaf + bool $inlineLeaf, + bool $forceLayout = false ): string { $owner = self::inlineOwner($source, $root, $segments, $from, $inlineLeaf); if ($owner === null || $from < $owner[0]) { @@ -1435,7 +2170,7 @@ private static function inlineOwner( bool $inlineLeaf ): ?array { if ($root['inline']) { - return self::lineOwner($source, $pos); + return self::inlineRange($root, $root, [], $source); } $node = $root; foreach ($segments as $seg) { @@ -1663,4 +2398,36 @@ private static function standalone( $out .= $newBody; return $out; } + + /** + * Apply insertion-specific layout policy to an already-built candidate. + * Integration point for insertSplice; insertion planning can call this + * without coupling its splice construction to replacement planning. + * + * @param string[] $parentSegments path to the containing Object + * @param array $replacement inserted cval + */ + public static function layoutInsertCandidate( + string $source, + string $candidate, + array $root, + array $parentSegments, + array $replacement, + int $from, + int $to, + int $inserted, + bool $inlineParent, + bool $forceLayout = false + ): string { + $insertForce = $forceLayout; + $lineTooWide = EditEnvelope::countScalars(EditTree::physicalLine($candidate, $from)) + > max(EditEnvelope::countScalars(EditTree::physicalLine($source, $from)), self::LINE_LIMIT); + if (!$insertForce && !$lineTooWide) { + return $candidate; + } + return self::layoutAdjust( + $source, $candidate, $root, $parentSegments, $replacement, + $from, $to, $inserted, $inlineParent + ); + } } diff --git a/src/Pure/Edit/EditTree.php b/src/Pure/Edit/EditTree.php index 76b0974..8f2ec5e 100644 --- a/src/Pure/Edit/EditTree.php +++ b/src/Pure/Edit/EditTree.php @@ -236,12 +236,16 @@ private function detectRoot(int $ts, int $te): bool // Empty inline root. $this->rootConsumed = true; $this->rootInline = self::compoundNode($kind); + $this->rootInline['inline'] = true; + $this->rootInline['rootRange'] = ['start' => $ts, 'end' => $te]; return true; } if ($this->src[$te - 1] === $closer) { // Closed inline root — position it and consume the document. $this->rootConsumed = true; $this->rootInline = $this->positionInline($ts, $te, $kind); + $this->rootInline['inline'] = true; + $this->rootInline['rootRange'] = ['start' => $ts, 'end' => $te]; return true; } // Unterminated inline root attempt: unreachable post-parse. @@ -650,38 +654,45 @@ private function buildInline(string $kind, array $segs, array $kids): array } /** - * Insert under an already-decoded inline key (no dotted expansion - * inside inline compounds — § 5.8 keys are single segments; - * post-parse duplicates are unreachable). + * Insert under an already-decoded inline key, expanding dotted paths + * according to the same key-path grammar used by block keys. * * @return void */ private function insertInlinePair(array &$table, string $rawKey, array $child) { - $d = PureScanner::decodeKeySegment($rawKey); - $key = isset($d['val']) && is_string($d['val']) ? $d['val'] : $rawKey; - $idx = self::findEntry($table, $key); - if ($idx !== null) { - // Reopen / duplicate: post-parse unreachable; mark the slot - // chain noncontiguous like the Rust descend would. - $table['pairs'][$idx][1]['slot'] = null; - if ($table['pairs'][$idx][1]['kind'] === 'object' && $child['kind'] === 'object') { - $sub = &$table['pairs'][$idx][1]; // in place: arrays copy - foreach ($child['pairs'] as $pair) { - $existing = self::findEntry($sub, $pair[0]); - if ($existing !== null) { - $sub['pairs'][$existing][1] = $pair[1]; - } else { - $sub['pairs'][] = $pair; - } + // Inline keys use the same quoted/escaped dotted path grammar as + // block keys. Split on structural dots, then expand intermediate + // segments into synthetic objects while keeping the physical slot + // (and inline flag) on the leaf only. + $segs = PureScanner::splitKeyPath($rawKey, 0, strlen($rawKey)); + $last = count($segs) - 1; + foreach ($segs as $i => $rawSeg) { + list($ss, $se) = PureScanner::trimBounds($rawSeg, 0, strlen($rawSeg)); + $trimmed = $ss >= $se ? '' : substr($rawSeg, $ss, $se - $ss); + $d = PureScanner::decodeKeySegment($trimmed); + $key = isset($d['val']) && is_string($d['val']) ? $d['val'] : $trimmed; + $idx = self::findEntry($table, $key); + if ($i === $last) { + if ($idx !== null) { + // Duplicate/conflicting paths cannot follow a successful + // parse; retain fail-closed positional behavior. + $table['pairs'][$idx][1] = $child; + } else { + $table['pairs'][] = [$key, $child]; } - unset($sub); return; } - $table['pairs'][$idx][1] = $child; - return; + if ($idx === null) { + $table['pairs'][] = [$key, self::compoundNode('object')]; + $idx = count($table['pairs']) - 1; + } elseif ($table['pairs'][$idx][1]['kind'] !== 'object') { + return; // unreachable after successful parse + } + // Descending/reopening invalidates the contiguous parent slot. + $table['pairs'][$idx][1]['slot'] = null; + $table = &$table['pairs'][$idx][1]; } - $table['pairs'][] = [$key, $child]; } /** @return bool */ diff --git a/src/PureBackend.php b/src/PureBackend.php index cbe4b01..c0a78a1 100644 --- a/src/PureBackend.php +++ b/src/PureBackend.php @@ -121,6 +121,42 @@ public static function editValueSegments(string $src, array $segments, $replacem return Pure\Edit\EditSplice::editValueSegments($src, $segments, $replacement); } + /** Pure insertion of a new final Object key. */ + public static function insertValue(string $src, string $path, $replacement): string + { + return Pure\Edit\EditSplice::insertValue($src, $path, $replacement); + } + + /** @param string[] $segments */ + public static function insertValueSegments(string $src, array $segments, $replacement): string + { + return Pure\Edit\EditSplice::insertValueSegments($src, array_values($segments), $replacement); + } + + /** Pure removal of an existing value. */ + public static function removeValue(string $src, string $path): string + { + return Pure\Edit\EditSplice::removeValue($src, $path); + } + + /** @param string[] $segments */ + public static function removeValueSegments(string $src, array $segments): string + { + return Pure\Edit\EditSplice::removeValueSegments($src, array_values($segments)); + } + + /** Pure rename of an existing Object key. */ + public static function renameKey(string $src, string $path, string $newKey): string + { + return Pure\Edit\EditSplice::renameKey($src, $path, $newKey); + } + + /** @param string[] $segments */ + public static function renameKeySegments(string $src, array $segments, string $newKey): string + { + return Pure\Edit\EditSplice::renameKeySegments($src, array_values($segments), $newKey); + } + /** * Pure-backend version marker (`pure-0.8.1` style) — never a * native version; the native one stays `Ktav::nativeVersion()`. diff --git a/tests/MutationNativeSpec.php b/tests/MutationNativeSpec.php new file mode 100644 index 0000000..fab16ca --- /dev/null +++ b/tests/MutationNativeSpec.php @@ -0,0 +1,484 @@ +getError(), ['EditInvalidPath', 'EditNotFound', 'EditAlreadyExists', 'EditUnsupported'], true)) { + throw $e; + } + } + }; + + $compareSuccess = function (callable $native, callable $pure, string $expected): void { + $n = $native(); + $p = $pure(); + expect($n)->toBe($expected); + expect($p)->toBe($expected); + }; + + $compareError = function (callable $native, callable $pure, string $expected) use ($requireMutationAbi): void { + $requireMutationAbi(); + $n = $p = null; + try { $native(); } catch (KtavException $e) { $n = $e; } + try { $pure(); } catch (KtavException $e) { $p = $e; } + expect($n)->toBeAnInstanceOf(KtavException::class); + expect($p)->toBeAnInstanceOf(KtavException::class); + expect($n->getError())->toBe($expected); + expect($p->getError())->toBe($expected); + expect($n->getError())->toBe($p->getError()); + expect($n->getBody())->toBe($p->getBody()); + expect($n->getErrorLine())->toBe($p->getErrorLine()); + expect($n->getSpan())->toBe($p->getSpan()); + expect($n->getMessage())->toBe($p->getMessage()); + expect($n->getReason())->toBe($p->getReason()); + expect($n->getPath())->toBe($p->getPath()); + expect($n->getLineText())->toBe($p->getLineText()); + expect($n->getCanonical())->toBe($p->getCanonical()); + expect($n->getSpecSection())->toBe($p->getSpecSection()); + }; + + it('uses root metadata for multiline layout after BOM and spaces', function () use ($requireMutationAbi) { + $requireMutationAbi(); + $source = "\xEF\xBB\xBF {x: 1}\r\n"; + $expected = "\xEF\xBB\xBF {\r\n x: 1\r\n y: ((\r\nfirst\r\nsecond\r\n ))\r\n}\r\n"; + $native = Ktav::insertValue($source, 'y', "first\nsecond"); + $pure = PureBackend::insertValueSegments($source, ['y'], "first\nsecond"); + expect($native)->toBe($expected); + expect($pure)->toBe($expected); + expect(Ktav::loads($native))->toBe(['x' => 1, 'y' => "first\nsecond"]); + expect(PureBackend::loads($pure))->toBe(['x' => 1, 'y' => "first\nsecond"]); + }); + + it('normalizes segment-array keys consistently across backends', function () use ($requireMutationAbi, $compareSuccess) { + $requireMutationAbi(); + $compareSuccess( + function () { return Ktav::insertValueSegments("cfg: {old: 1}\n", ['parent' => 'cfg', 'leaf' => 'new'], 2); }, + function () { return PureBackend::insertValueSegments("cfg: {old: 1}\n", ['parent' => 'cfg', 'leaf' => 'new'], 2); }, + "cfg: {old: 1, new: 2}\n" + ); + $compareSuccess( + function () { return Ktav::removeValueSegments("cfg: {old: 1}\n", ['parent' => 'cfg', 'leaf' => 'old']); }, + function () { return PureBackend::removeValueSegments("cfg: {old: 1}\n", ['parent' => 'cfg', 'leaf' => 'old']); }, + "cfg: {}\n" + ); + $compareSuccess( + function () { return Ktav::renameKeySegments("cfg: {old: 1}\n", ['parent' => 'cfg', 'leaf' => 'old'], 'renamed'); }, + function () { return PureBackend::renameKeySegments("cfg: {old: 1}\n", ['parent' => 'cfg', 'leaf' => 'old'], 'renamed'); }, + "cfg: {renamed: 1}\n" + ); + }); + + it('matches shared native and pure inline mutation fixtures', function () use ($requireMutationAbi, $compareSuccess, $compareError) { + $requireMutationAbi(); + $src = "cfg: {a.b: 1, a.c: 2}\n"; + $compareSuccess( + function () use ($src) { return Ktav::renameKey($src, 'cfg.a.b', 'd'); }, + function () use ($src) { return PureBackend::renameKey($src, 'cfg.a.b', 'd'); }, + "cfg: {a.d: 1, a.c: 2}\n" + ); + $compareError( + function () use ($src) { return Ktav::removeValue($src, 'cfg.a.b'); }, + function () use ($src) { return PureBackend::removeValue($src, 'cfg.a.b'); }, + 'EditUnsupported' + ); + $src = "cfg: {a.b: 1}\n"; + $compareError( + function () use ($src) { return Ktav::insertValue($src, 'cfg.a.x', 2); }, + function () use ($src) { return PureBackend::insertValue($src, 'cfg.a.x', 2); }, + 'EditUnsupported' + ); + + $quoted = "cfg: {\"a.b\": 1, c: 2}\n"; + $compareSuccess( + function () use ($quoted) { return Ktav::renameKey($quoted, 'cfg.a\\.b', 'd'); }, + function () use ($quoted) { return PureBackend::renameKey($quoted, 'cfg.a\\.b', 'd'); }, + "cfg: {d: 1, c: 2}\n" + ); + $compareSuccess( + function () use ($quoted) { return Ktav::removeValue($quoted, 'cfg.a\\.b'); }, + function () use ($quoted) { return PureBackend::removeValue($quoted, 'cfg.a\\.b'); }, + "cfg: {c: 2}\n" + ); + $src = "cfg: {a: p\\,}\n"; + $compareSuccess( + function () use ($src) { return Ktav::insertValue($src, 'cfg.b', 2); }, + function () use ($src) { return PureBackend::insertValue($src, 'cfg.b', 2); }, + "cfg: {a: p\\,, b: 2}\n" + ); + $src = "cfg: {a: 1, }\n"; + $compareSuccess( + function () use ($src) { return Ktav::insertValue($src, 'cfg.b', 2); }, + function () use ($src) { return PureBackend::insertValue($src, 'cfg.b', 2); }, + "cfg: {a: 1, b: 2, }\n" + ); + $src = "\xEF\xBB\xBFfirst: 1\r\ncfg: [{a: 1,}]\nlast: 2\r"; + $expected = "\xEF\xBB\xBFfirst: 1\r\ncfg: [{a: 1, b: 2,}]\nlast: 2\r"; + $compareSuccess( + function () use ($src) { return Ktav::insertValue($src, 'cfg.0.b', 2); }, + function () use ($src) { return PureBackend::insertValue($src, 'cfg.0.b', 2); }, + $expected + ); + }); + + it('covers root comments/braces, BOM spacing, EOL mutation and root-array removal', function () use ($requireMutationAbi, $compareSuccess) { + $requireMutationAbi(); + $src = "\n## { lead }\n{a: 1}\n"; + $expected = "\n## { lead }\n{a: 1, b: 2}\n"; + $compareSuccess( + function () use ($src) { return Ktav::insertValue($src, 'b', 2); }, + function () use ($src) { return PureBackend::insertValue($src, 'b', 2); }, + $expected + ); + expect(Ktav::loads(Ktav::insertValue($src, 'b', 2)))->toBe(['a' => 1, 'b' => 2]); + expect(PureBackend::loads(PureBackend::insertValue($src, 'b', 2)))->toBe(['a' => 1, 'b' => 2]); + $src = "\xEF\xBB\xBF {a: 1}\r\n"; + $expected = "\xEF\xBB\xBF {a: 1, b: 2}\r\n"; + $compareSuccess( + function () use ($src) { return Ktav::insertValue($src, 'b', 2); }, + function () use ($src) { return PureBackend::insertValue($src, 'b', 2); }, + $expected + ); + expect(Ktav::loads(Ktav::insertValue($src, 'b', 2)))->toBe(['a' => 1, 'b' => 2]); + expect(PureBackend::loads(PureBackend::insertValue($src, 'b', 2)))->toBe(['a' => 1, 'b' => 2]); + $src = "\xE2\x80\x83## { Unicode }\r\n{a: 1}\r\n"; + $expected = "\xE2\x80\x83## { Unicode }\r\n{a: 1, b: 2}\r\n"; + $compareSuccess( + function () use ($src) { return Ktav::insertValue($src, 'b', 2); }, + function () use ($src) { return PureBackend::insertValue($src, 'b', 2); }, + $expected + ); + expect(Ktav::loads(Ktav::insertValue($src, 'b', 2)))->toBe(['a' => 1, 'b' => 2]); + expect(PureBackend::loads(PureBackend::insertValue($src, 'b', 2)))->toBe(['a' => 1, 'b' => 2]); + $src = "obj: {a: 1}\r\n"; + $expected = "obj: {}\r\n"; + $compareSuccess( + function () use ($src) { return Ktav::removeValue($src, 'obj.a'); }, + function () use ($src) { return PureBackend::removeValue($src, 'obj.a'); }, + $expected + ); + expect(Ktav::loads($expected))->toBe(['obj' => []]); + $src = "[1, 2]"; + $expected = "[2]"; + $compareSuccess( + function () use ($src) { return Ktav::removeValue($src, '0'); }, + function () use ($src) { return PureBackend::removeValue($src, '0'); }, + $expected + ); + expect(Ktav::loads(Ktav::removeValue($src, '0')))->toBe([2]); + expect(PureBackend::loads(PureBackend::removeValue($src, '0')))->toBe([2]); + + $src = "\n## { lead }\r\n{a: 1, b: 2}\n"; + $native = Ktav::removeValue($src, 'a'); + $pure = PureBackend::removeValue($src, 'a'); + expect($native)->toBe("\n## { lead }\r\n{b: 2}\n"); + expect($pure)->toBe("\n## { lead }\r\n{b: 2}\n"); + expect(Ktav::loads($native))->toBe(['b' => 2]); + expect(PureBackend::loads($pure))->toBe(['b' => 2]); + + $src = "\xEF\xBB\xBF \n## { array lead }\r\n[1, 2]\n"; + $native = Ktav::removeValue($src, '0'); + $pure = PureBackend::removeValue($src, '0'); + expect($native)->toBe("\xEF\xBB\xBF \n## { array lead }\r\n[2]\n"); + expect($pure)->toBe("\xEF\xBB\xBF \n## { array lead }\r\n[2]\n"); + expect(Ktav::loads($native))->toBe([2]); + expect(PureBackend::loads($pure))->toBe([2]); + }); + + it('checks parsed native mutation output independently of backend parity', function () use ($requireMutationAbi) { + $requireMutationAbi(); + $large = Ktav::insertValue("base: 0\n", 'n', 9007199254740993); + expect(Ktav::loads($large)['n'])->toBe(9007199254740993); + + $utf8 = "雪: 1\na: 2\n"; + expect(Ktav::loads(Ktav::removeValue($utf8, 'a')))->toBe(['雪' => 1]); + expect(Ktav::loads(Ktav::removeValue("[1, 2, 3]\n", '0')))->toBe([2, 3]); + expect(Ktav::loads(Ktav::removeValue("outer: {inner: {leaf: 1}}\n", 'outer.inner.leaf'))) + ->toBe(['outer' => ['inner' => []]]); + }); + + it('checks no-prune removal and invalid-path offset envelope parity', function () use ($requireMutationAbi, $compareSuccess) { + $requireMutationAbi(); + $src = "a: {b: {c: 1}}\n"; + $compareSuccess( + function () use ($src) { return Ktav::removeValue($src, 'a.b.c'); }, + function () use ($src) { return PureBackend::removeValue($src, 'a.b.c'); }, + "a: {b: {}}\n" + ); + $native = $pure = null; + try { Ktav::removeValue("a: 1\n", "é\\x"); } catch (KtavException $e) { $native = $e; } + try { PureBackend::removeValue("a: 1\n", "é\\x"); } catch (KtavException $e) { $pure = $e; } + expect($native)->toBeAnInstanceOf(KtavException::class); + expect($pure)->toBeAnInstanceOf(KtavException::class); + $expected = 'invalid edit path (bad escape or empty segment) at byte 2'; + foreach ([$native, $pure] as $error) { + expect($error->getError())->toBe('EditInvalidPath'); + expect($error->getBody())->toBe('2'); + expect($error->getMessage())->toBe($expected); + expect($error->getErrorLine())->toBe(null); + expect($error->getSpan())->toBe(null); + } + }); + + it('inserts into an inline Object using the Rust lossless splice oracle', function () use ($requireMutationAbi, $compareSuccess) { + $requireMutationAbi(); + $src = "settings: {old: +01}\n"; + $expected = "settings: {old: +01, new: 2}\n"; + $compareSuccess( + function () use ($src) { return Ktav::insertValue($src, 'settings.new', 2); }, + function () use ($src) { return PureBackend::insertValue($src, 'settings.new', 2); }, + $expected + ); + }); + + it('inserts a missing key and fails explicitly on collision', function () use ($requireMutationAbi, $compareSuccess, $compareError) { + $requireMutationAbi(); + $src = "## heading\nsettings: {old: +01}\n## tail\n"; + $compareSuccess( + function () use ($src) { return Ktav::insertValue($src, 'settings.new', 2); }, + function () use ($src) { return PureBackend::insertValue($src, 'settings.new', 2); }, + "## heading\nsettings: {old: +01, new: 2}\n## tail\n" + ); + $compareError( + function () { return Ktav::insertValue("a: 1\n", 'a', 2); }, + function () { return PureBackend::insertValue("a: 1\n", 'a', 2); }, + 'EditAlreadyExists' + ); + }); + + it('covers both path forms, ## lossless comments and array removal oracles', function () use ($requireMutationAbi, $compareSuccess, $compareError) { + $requireMutationAbi(); + $compareSuccess( + function () { return Ktav::insertValue("a: 1\n", 'a\\.b', 2); }, + function () { return PureBackend::insertValue("a: 1\n", 'a\\.b', 2); }, + "a: 1\n\"a.b\": 2\n" + ); + $compareSuccess( + function () { return Ktav::insertValueSegments("a: 1\n", ['a.b'], 2); }, + function () { return PureBackend::insertValueSegments("a: 1\n", ['a.b'], 2); }, + "a: 1\n\"a.b\": 2\n" + ); + $src = "## top\na: 1\n## mid\nb: 2\n## end\n"; + $compareSuccess( + function () { return Ktav::insertValueSegments("a: 1 +", ['a.b'], 2); }, + function () { return PureBackend::insertValueSegments("a: 1 +", ['a.b'], 2); }, + "a: 1 +\"a.b\": 2 +" + ); + $src = "## top +a: 1 +## mid +b: 2 +## end +"; + $compareSuccess( + function () use ($src) { return Ktav::removeValue($src, 'a'); }, + function () use ($src) { return PureBackend::removeValue($src, 'a'); }, + "## top\n## mid\nb: 2\n## end\n" + ); + $commented = "a: {\n ## inner\n x: 1\n}\n"; + $compareSuccess( + function () use ($commented) { return Ktav::renameKey($commented, 'a.x', 'y'); }, + function () use ($commented) { return PureBackend::renameKey($commented, 'a.x', 'y'); }, + "a: {\n ## inner\n y: 1\n}\n" + ); + $compareError( + function () use ($commented) { return Ktav::removeValue($commented, 'a'); }, + function () use ($commented) { return PureBackend::removeValue($commented, 'a'); }, + 'EditUnsupported' + ); + }); + + it('removes the addressed terminal value and keeps siblings', function () use ($requireMutationAbi, $compareSuccess) { + $requireMutationAbi(); + $src = "a: 1\nb: 2\nc: 3\n"; + $compareSuccess( + function () use ($src) { return Ktav::removeValue($src, 'b'); }, + function () use ($src) { return PureBackend::removeValue($src, 'b'); }, + "a: 1\nc: 3\n" + ); + $src = "a.b: 1\n"; + $compareSuccess( + function () use ($src) { return Ktav::removeValue($src, 'a.b'); }, + function () use ($src) { return PureBackend::removeValue($src, 'a.b'); }, + "a: {}\n" + ); + $src = "obj: {\n \"a.b\": 1\n c: 2\n}\n"; + $compareSuccess( + function () use ($src) { return Ktav::removeValueSegments($src, ['obj', 'a.b']); }, + function () use ($src) { return PureBackend::removeValueSegments($src, ['obj', 'a.b']); }, + "obj: {\n c: 2\n}\n" + ); + }); + + it('renames via textual and literal-segment paths with literal dotted new keys', function () use ($requireMutationAbi, $compareSuccess) { + $requireMutationAbi(); + $src = "obj: {\n \"a.b\": 1\n keep: 2\n}\n"; + $expected = "obj: {\n \"new.name\": 1\n keep: 2\n}\n"; + $compareSuccess( + function () use ($src) { return Ktav::renameKey($src, 'obj.a\\.b', 'new.name'); }, + function () use ($src) { return PureBackend::renameKey($src, 'obj.a\\.b', 'new.name'); }, + $expected + ); + $compareSuccess( + function () use ($src) { return Ktav::renameKeySegments($src, ['obj', 'a.b'], 'new.name'); }, + function () use ($src) { return PureBackend::renameKeySegments($src, ['obj', 'a.b'], 'new.name'); }, + $expected + ); + }); + + it('covers quoted inline members, escaped commas and ArrayObject mutation parity', function () use ($requireMutationAbi, $compareSuccess) { + $requireMutationAbi(); + $compareSuccess( + function () { return Ktav::insertValue("a: {x: 1}\n", 'a.k', 'p,q'); }, + function () { return PureBackend::insertValue("a: {x: 1}\n", 'a.k', 'p,q'); }, + "a: {x: 1, k: p\\,q}\n" + ); + $arrayObject = new \ArrayObject(['x' => 1, 'y' => 2]); + $expected = "base: 0\nobj: {\n x: 1\n y: 2\n}\n"; + $compareSuccess( + function () use ($arrayObject) { return Ktav::insertValue("base: 0\n", 'obj', $arrayObject); }, + function () use ($arrayObject) { return PureBackend::insertValue("base: 0\n", 'obj', $arrayObject); }, + $expected + ); + }); + + it('preserves trailing commas, UTF-8, i64 values and untouched source spelling', function () use ($requireMutationAbi, $compareSuccess, $compareError) { + $requireMutationAbi(); + $src = "a: {old: +01,}\n"; + $compareSuccess( + function () use ($src) { return Ktav::insertValue($src, 'a.new', 9223372036854775807); }, + function () use ($src) { return PureBackend::insertValue($src, 'a.new', 9223372036854775807); }, + "a: {old: +01, new: 9223372036854775807,}\n" + ); + expect(Ktav::loads("n: 9223372036854775807\n"))->toBe(['n' => 9223372036854775807]); + expect(PureBackend::loads("n: 9223372036854775807\n"))->toBe(['n' => 9223372036854775807]); + $src = "a: {old: +01}\n"; + $compareSuccess( + function () use ($src) { return Ktav::renameKey($src, 'a.old', 'new'); }, + function () use ($src) { return PureBackend::renameKey($src, 'a.old', 'new'); }, + "a: {new: +01}\n" + ); + $src = "a: {old: +01}\n"; + $compareSuccess( + function () use ($src) { return Ktav::removeValue($src, 'a.old'); }, + function () use ($src) { return PureBackend::removeValue($src, 'a.old'); }, + "a: {}\n" + ); + $src = "a: {old: +01}\n"; + $compareSuccess( + function () use ($src) { return Ktav::insertValue($src, 'a.雪', 'café'); }, + function () use ($src) { return PureBackend::insertValue($src, 'a.雪', 'café'); }, + "a: {old: +01, 雪: café}\n" + ); + $compareSuccess( + function () { return Ktav::insertValue("a: {old: +01,}\n", 'a.new', 9223372036854775807); }, + function () { return PureBackend::insertValue("a: {old: +01,}\n", 'a.new', 9223372036854775807); }, + "a: {old: +01, new: 9223372036854775807,}\n" + ); + $mutated = Ktav::insertValue("base: 0\n", 'n', 9007199254740993); + expect(Ktav::loads($mutated)['n'])->toBe(9007199254740993); + expect(PureBackend::loads(PureBackend::insertValue("base: 0\n", 'n', 9007199254740993))['n']) + ->toBe(9007199254740993); + $invalidUtf8 = "a: \xE2\x82\n"; + $compareError( + function () use ($invalidUtf8) { return Ktav::insertValue($invalidUtf8, 'a.new', 1); }, + function () use ($invalidUtf8) { return PureBackend::insertValue($invalidUtf8, 'a.new', 1); }, + 'InvalidUtf8' + ); + $compareError( + function () use ($invalidUtf8) { return Ktav::insertValue($invalidUtf8, '', 1); }, + function () use ($invalidUtf8) { return PureBackend::insertValue($invalidUtf8, '', 1); }, + 'InvalidUtf8' + ); + }); + + it('matches invalid UTF-8 transport diagnostics and source-first validation', function () use ($requireMutationAbi) { + $requireMutationAbi(); + $cases = [ + ["\xFF\x80", 'invalid utf-8 sequence of 1 bytes from index 0'], ["\x80", 'invalid utf-8 sequence of 1 bytes from index 0'], + ["\xC2A", 'invalid utf-8 sequence of 1 bytes from index 0'], ["\xE2\x82A", 'invalid utf-8 sequence of 2 bytes from index 0'], ["\xE0\x80", 'invalid utf-8 sequence of 1 bytes from index 0'], + ["\xED\xA0", 'invalid utf-8 sequence of 1 bytes from index 0'], ["\xF0\x80", 'invalid utf-8 sequence of 1 bytes from index 0'], + ["\xF0\x9F\x92A", 'invalid utf-8 sequence of 3 bytes from index 0'], + ["\xF4\x8F\x80", 'incomplete utf-8 byte sequence from index 0'], + ["\xF4\x90\x80\x80", 'invalid utf-8 sequence of 1 bytes from index 0'], + ["x\xE2\x82A", 'invalid utf-8 sequence of 2 bytes from index 1'], + ["\xE2\x82", 'incomplete utf-8 byte sequence from index 0'], ["x\xF0\x9F\x92", 'incomplete utf-8 byte sequence from index 1'], + ]; + foreach ($cases as [$bad, $detail]) { + foreach ([ + [function () use ($bad) { return Ktav::removeValue("a: 1\n", $bad); }, function () use ($bad) { return PureBackend::removeValue("a: 1\n", $bad); }, 'path is not valid UTF-8: ' . $detail], + [function () use ($bad) { return Ktav::renameKey("a: 1\n", 'a', $bad); }, function () use ($bad) { return PureBackend::renameKey("a: 1\n", 'a', $bad); }, 'new key is not valid UTF-8: ' . $detail], + ] as [$native, $pure, $message]) { + foreach ([$native, $pure] as $call) { + $error = null; + try { $call(); } catch (KtavException $e) { $error = $e; } + expect($error)->toBeAnInstanceOf(KtavException::class); + expect($error->getError())->toBe('Message'); + expect($error->getMessage())->toBe($message); + expect($error->getBody())->toBe($message); + expect($error->getErrorLine())->toBe(null); + expect($error->getSpan())->toBe(null); + expect($error->getPath())->toBe(null); + expect($error->getReason())->toBe(null); + expect($error->getLineText())->toBe(null); + expect($error->getCanonical())->toBe(null); + expect($error->getSpecSection())->toBe(null); + } + } + } + $source = "a: {\n"; + foreach ([ + [function () { return Ktav::removeValue("a: {\n", "\xFF\x80"); }, function () { return PureBackend::removeValue("a: {\n", "\xFF\x80"); }], + [function () { return Ktav::renameKey("a: {\n", 'a', "\xFF\x80"); }, function () { return PureBackend::renameKey("a: {\n", 'a', "\xFF\x80"); }], + ] as [$native, $pure]) { + foreach ([$native, $pure] as $call) { + $error = null; + try { $call(); } catch (KtavException $e) { $error = $e; } + expect($error)->toBeAnInstanceOf(KtavException::class); + expect($error->getError())->toBe('UnclosedCompound'); + } + } + }); + + it('matches typed errors and source-first parser diagnostics', function () use ($requireMutationAbi, $compareError) { + $compareError( + function () { return Ktav::removeValue("a: 1\n", 'missing'); }, + function () { return PureBackend::removeValue("a: 1\n", 'missing'); }, + 'EditNotFound' + ); + $compareError( + function () { return Ktav::renameKey("a: 1\nb: 2\n", 'a', 'b'); }, + function () { return PureBackend::renameKey("a: 1\nb: 2\n", 'a', 'b'); }, + 'EditAlreadyExists' + ); + $compareError( + function () { return Ktav::renameKey("a: 1\n", 'a', ''); }, + function () { return PureBackend::renameKey("a: 1\n", 'a', ''); }, + 'EditUnsupported' + ); + $compareError( + function () { return Ktav::renameKey("a: {\n", 'a.', 'b'); }, + function () { return PureBackend::renameKey("a: {\n", 'a.', 'b'); }, + 'UnclosedCompound' + ); + }); +}); diff --git a/tests/Pure/InsertMutationSpec.php b/tests/Pure/InsertMutationSpec.php new file mode 100644 index 0000000..7902d7e --- /dev/null +++ b/tests/Pure/InsertMutationSpec.php @@ -0,0 +1,127 @@ +toBeAnInstanceOf(KtavException::class); + expect($caught->getError())->toBe($error); + return $caught; + }; + + it('matches inline dotted-path mutation support boundaries from Rust', function () use ($fails) { + expect(PureBackend::renameKey("cfg: {a.b: 1, a.c: 2}\n", 'cfg.a.b', 'd')) + ->toBe("cfg: {a.d: 1, a.c: 2}\n"); + $fails(static function () { + PureBackend::removeValue("cfg: {a.b: 1, a.c: 2}\n", 'cfg.a.b'); + }, 'EditUnsupported'); + $fails(static function () { + PureBackend::insertValue("cfg: {a.b: 1}\n", 'cfg.a.x', 2); + }, 'EditUnsupported'); + }); + + it('splices quoted literal-dot keys, escaped terminal commas, and spaced structural trailing commas', function () use ($insert, $fails) { + $quoted = "cfg: {\"a.b\": 1, c: 2}\n"; + expect(PureBackend::renameKey($quoted, 'cfg.a\\.b', 'd')) + ->toBe("cfg: {d: 1, c: 2}\n"); + expect(PureBackend::removeValue($quoted, 'cfg.a\\.b')) + ->toBe("cfg: {c: 2}\n"); + + expect($insert("cfg: {a: p\\,}\n", 'cfg.b', 2)) + ->toBe("cfg: {a: p\\,, b: 2}\n"); + expect($insert("cfg: {a: 1, }\n", 'cfg.b', 2)) + ->toBe("cfg: {a: 1, b: 2, }\n"); + }); + + it('preserves mixed EOLs and BOM while mutating an Object nested in an Array', function () use ($insert) { + $source = "\xEF\xBB\xBFfirst: 1\r\ncfg: [{a: 1,}]\nlast: 2\r"; + expect($insert($source, 'cfg.0.b', 2)) + ->toBe("\xEF\xBB\xBFfirst: 1\r\ncfg: [{a: 1, b: 2,}]\nlast: 2\r"); + }); + + it('returns the Rust Unsupported oracle for inline dotted mutation paths', function () use ($fails) { + $fails(static function () { + PureBackend::removeValue("cfg: {a.b: 1, a.c: 2}\n", 'cfg.a.b'); + }, 'EditUnsupported'); + }); + + it('matches root EOL, comment, BOM and empty-root insertion oracles', function () use ($insert) { + expect($insert("a: 1\n", 'b', 2))->toBe("a: 1\nb: 2\n"); + expect($insert('a: 1', 'b', 'v'))->toBe("a: 1\nb: v"); + expect($insert("a: 1\n## tail\n", 'b', 'v'))->toBe("a: 1\n## tail\nb: v\n"); + expect($insert("a: 1\r\n", 'b', 'v'))->toBe("a: 1\r\nb: v\r\n"); + expect($insert("a: 1\rb: 2", 'c', 'v'))->toBe("a: 1\rb: 2\rc: v"); + expect($insert("\xEF\xBB\xBFa: 1\n", 'b', 'v'))->toBe("\xEF\xBB\xBFa: 1\nb: v\n"); + expect($insert("## header\n", 'k', 'v'))->toBe("## header\nk: v\n"); + expect($insert("\xEF\xBB\xBF", 'k', 'v'))->toBe("\xEF\xBB\xBF\nk: v"); + expect($insert("{}\n", 'k', 1))->toBe("{k: 1}\n"); + expect($insert('{}', 'k', 'v'))->toBe('{k: v}'); + expect($insert("{\n}\n", 'k', 'v'))->toBe("{\n k: v\n}\n"); + expect($insert("a.b: 1\na.c: 2\n", 'd', 'v'))->toBe("a.b: 1\na.c: 2\nd: v\n"); + }); + + it('matches block, inline and array-object layout oracles', function () use ($insert) { + expect($insert("a: {\n x: 1\n}\nb: 2\n", 'a.k', 'v'))->toBe("a: {\n x: 1\n k: v\n}\nb: 2\n"); + expect($insert("a: {\n}\n", 'a.k', 'v'))->toBe("a: {\n k: v\n}\n"); + expect($insert("a: {\r\n}\r\n", 'a.k', 'v'))->toBe("a: {\r\n k: v\r\n}\r\n"); + expect($insert("a: {x: 1,}\n", 'a.k', 2))->toBe("a: {x: 1, k: 2,}\n"); + expect($insert("a: {x: 1}\n", 'a.k', 'é雪'))->toBe("a: {x: 1, k: é雪}\n"); + expect($insert("a: {}\n", 'a.k', 'v'))->toBe("a: {k: v}\n"); + expect($insert("a: {x: 1}\n", 'a.k', 9223372036854775807))->toBe("a: {x: 1, k: 9223372036854775807}\n"); + $mutatedI64 = $insert("base: 0\n", 'n', 9007199254740993); + expect(PureBackend::loads($mutatedI64)['n'])->toBe(9007199254740993); + expect(PureBackend::loads("n: 9223372036854775807\n")['n'])->toBe(9223372036854775807); + expect($insert("a: {x: +01}\n", 'a.k', 2))->toBe("a: {x: +01, k: 2}\n"); + expect($insert("a: {x: 1}\n", 'a.k', 'p,q'))->toBe("a: {x: 1, k: p\\,q}\n"); + expect($insert("a: {x: 1}\n", 'a.k', '42'))->toBe("a: {x: 1, k: \\u00342}\n"); + expect($insert("a: {x: 1}\n", 'a.k', "p\nq"))->toBe("a: {\n x: 1\n k: ((\np\nq\n ))\n}\n"); + expect($insert("top: [{a: 1}]\n", 'top.0.c', 'v'))->toBe("top: [{a: 1, c: v}]\n"); + expect($insert("top: [\n {\n a: 1\n }\n]\n", 'top.0.b', 'v'))->toBe("top: [\n {\n a: 1\n b: v\n }\n]\n"); + expect($insert("a: 1\n", 'n', ['x' => 1, 'y' => 'z']))->toBe("a: 1\nn: {\n x: 1\n y: z\n}\n"); + expect($insert("a: {x: 1}\n", 'a.k', "a\rb"))->toBe("a: {x: 1, k: a\\rb}\n"); + expect($insert("a: {x: 1}\n", 'a.k', "a\n))\nb"))->toBe("a: {x: 1, k: a\\n))\\nb}\n"); + expect($insert("o: {i: {x: 1}}\n", 'o.i.k', "p\nq"))->toBe("o: {\n i: {\n x: 1\n k: ((\np\nq\n ))\n }\n}\n"); + expect($insert("a: {}\n", 'a.k', str_repeat('x', 101)))->toBe("a: {\n k: " . str_repeat('x', 101) . "\n}\n"); + }); + + it('quotes or escapes keys and treats segments as literal keys', function () use ($insert, $segments) { + expect($insert("a: 1\n", 'a\\.b', 'v'))->toBe("a: 1\n\"a.b\": v\n"); + expect($segments("a: 1\n", ['a.b'], 'v'))->toBe("a: 1\n\"a.b\": v\n"); + expect($insert("a: 1\n", 'x,y', 'v'))->toBe("a: 1\n\"x,y\": v\n"); + expect($segments("k: 1\n", ['x\\y'], 'v'))->toBe("k: 1\nx\\\\y: v\n"); + expect($insert("a: 1\n", '0', 'v'))->toBe("a: 1\n0: v\n"); + }); + + it('preserves comments and ignores braces in comments in block insertion', function () use ($insert) { + foreach (["\n", "\r\n", "\r"] as $eol) { + $source = "## { header{$eol}{{$eol}}{$eol}## tail{$eol}"; + expect($insert($source, 'k', 'v'))->toBe("## { header{$eol}{{$eol} k: v{$eol}}{$eol}## tail{$eol}"); + } + }); + + it('returns the insertion error oracles without overwriting', function () use ($insert, $segments, $fails) { + $e = $fails(static function () use ($insert) { $insert("a: 1\n", 'a', 'x'); }, 'EditAlreadyExists'); + expect($e->getMessage())->toBe('edit target already exists; insertion never overwrites'); + $fails(static function () use ($insert) { $insert("a: 1\n", 'b.c', 'v'); }, 'EditNotFound'); + $fails(static function () use ($insert) { $insert("a: 1\n", 'a.c', 'v'); }, 'EditNotFound'); + $fails(static function () use ($segments) { $segments("a: 1\n", [], 'v'); }, 'EditNotFound'); + $fails(static function () use ($insert) { $insert("a: 1\n", '', 'v'); }, 'EditInvalidPath'); + $fails(static function () use ($insert) { $insert("list: [x]\n", 'list.1', 'v'); }, 'EditUnsupported'); + $fails(static function () use ($insert) { $insert("a: {y: 1}\n", 'a.y', 'v'); }, 'EditAlreadyExists'); + $fails(static function () use ($insert) { $insert("a: {\n", 'k', 'v'); }, 'UnclosedCompound'); + $fails(static function () use ($insert) { $insert("a: \xFF\n", 'k', 'v'); }, 'InvalidUtf8'); + }); +}); diff --git a/tests/Pure/MutationSpec.php b/tests/Pure/MutationSpec.php new file mode 100644 index 0000000..50b4924 --- /dev/null +++ b/tests/Pure/MutationSpec.php @@ -0,0 +1,187 @@ +toBe("settings: {old: +01, new: 2}\n"); + }); + + it('inserts through textual and literal-segment paths and preserves ## comments', function () { + expect(PureBackend::insertValue("a: 1 +", 'a\.b', 2))->toBe("a: 1 +\"a.b\": 2 +"); + expect(PureBackend::insertValueSegments("a: 1 +", ['a.b'], 2))->toBe("a: 1 +\"a.b\": 2 +"); + expect(PureBackend::insertValue("## head +a: 1 +## tail +", 'b', 2)) + ->toBe("## head +a: 1 +## tail +b: 2 +"); + }); + + it('inserts a missing final Object key without disturbing surrounding comments or spelling', function () { + $src = "## heading\nsettings: {old: +01}\n## tail\n"; + expect(PureBackend::insertValue($src, 'settings.new', 2)) + ->toBe("## heading\nsettings: {old: +01, new: 2}\n## tail\n"); + }); + + it('handles ArrayObject values', function () { + expect(PureBackend::insertValue("base: 0\n", 'obj', new \ArrayObject(['x' => 1, 'y' => 2]))) + ->toBe("base: 0\nobj: {\n x: 1\n y: 2\n}\n"); + }); + + it('uses an independent expected string for trailing-comma insertion and tests no-op rename bytes', function () { + $src = "first: 1\nobj: {a: +01, b: 2,}\nlast: 3"; + expect(PureBackend::renameKey($src, 'obj.a', 'a'))->toBe($src); + expect(PureBackend::insertValue("obj: {a: +01,}\n", 'obj.b', 2)) + ->toBe("obj: {a: +01, b: 2,}\n"); + }); + + it('checks mutation semantics by parsing actual output, including i64 and removal boundaries', function () { + $inserted = PureBackend::insertValue("base: 0\n", 'n', 9007199254740993); + expect(PureBackend::loads($inserted)['n'])->toBe(9007199254740993); + + $utf8 = "雪: 1\na: 2\n"; + $removed = PureBackend::removeValue($utf8, 'a'); + expect(PureBackend::loads($removed))->toBe(['雪' => 1]); + + $rootArray = PureBackend::removeValue("[1, 2, 3]\n", '0'); + expect(PureBackend::loads($rootArray))->toBe([2, 3]); + + $dotted = PureBackend::removeValue("a.b: 1\n", 'a.b'); + expect($dotted)->toBe("a: {}\n"); + + expect(PureBackend::loads($dotted))->toBe(['a' => []]); + }); + + it('covers root whitespace/comments with braces, BOM spacing, and mutation EOLs', function () { + $cases = [ + ["\n## { lead }\nobj: {a: 1}\n", 'obj.b', 2, "\n## { lead }\nobj: {a: 1, b: 2}\n", ['obj' => ['a' => 1, 'b' => 2]]], + ["\xEF\xBB\xBF a: 1\r\n", 'b', 2, "\xEF\xBB\xBF a: 1\r\nb: 2\r\n", ['a' => 1, 'b' => 2]], + ]; + foreach ($cases as [$src, $path, $value, $expected, $semantic]) { + $actual = PureBackend::insertValue($src, $path, $value); + expect($actual)->toBe($expected); + if ($semantic !== null) { expect(PureBackend::loads($actual))->toBe($semantic); } + } + $actual = PureBackend::insertValue("\xE2\x80\x83## { Unicode whitespace }\r\n{a: 1}\r\n", 'b', 2); + expect($actual)->toBe("\xE2\x80\x83## { Unicode whitespace }\r\n{a: 1, b: 2}\r\n"); + expect(PureBackend::loads($actual))->toBe(['a' => 1, 'b' => 2]); + $eol = "obj: {a: 1}\r\n"; + $removed = PureBackend::removeValue($eol, 'obj.a'); + expect($removed)->toBe("obj: {}\r\n"); + expect(PureBackend::loads($removed))->toBe(['obj' => []]); + $root = PureBackend::removeValue("[1, 2, 3]\r", '1'); + expect($root)->toBe("[1, 3]\r"); + expect(PureBackend::loads($root))->toBe([1, 3]); + }); + + it('does not prune empty ancestors after removal', function () { + expect(PureBackend::removeValue("a: {b: {c: 1}}\n", 'a.b.c')) + ->toBe("a: {b: {}}\n"); + expect(PureBackend::removeValue("a.b: 1\n", 'a.b')) + ->toBe("a: {}\n"); + }); + + it('reports invalid textual path byte offsets after multibyte segments', function () { + $caught = null; + try { PureBackend::removeValue("a: 1\n", "é\\x"); } catch (KtavException $e) { $caught = $e; } + expect($caught)->toBeAnInstanceOf(KtavException::class); + expect($caught->getError())->toBe('EditInvalidPath'); + expect($caught->getBody())->toBe('2'); + expect($caught->getMessage())->toBe('invalid edit path (bad escape or empty segment) at byte 2'); + }); + + it('removes an existing value at the path end while retaining its siblings and comments', function () { + $src = "a: 1\nb: 2\nc: 3\n"; + expect(PureBackend::removeValue($src, 'b'))->toBe("a: 1\nc: 3\n"); + expect(PureBackend::removeValueSegments("obj: {\n \"a.b\": 1\n c: 2\n}\n", ['obj', 'a.b'])) + ->toBe("obj: {\n c: 2\n}\n"); + }); + + it('removes with textual paths and preserves comments around the removed member', function () { + expect(PureBackend::removeValue("## top\na: 1\n## mid\nb: 2\n## end\n", 'a')) + ->toBe("## top\n## mid\nb: 2\n## end\n"); + expect(PureBackend::removeValue("a: [1, 2, 3]\n", 'a.1'))->toBe("a: [1, 3]\n"); + }); + + it('renames by textual path and literal segments; new key is one decoded key', function () { + $src = "obj: {\n \"a.b\": 1\n keep: 2\n}\n"; + expect(PureBackend::renameKey($src, 'obj.a\\.b', 'new.name')) + ->toBe("obj: {\n \"new.name\": 1\n keep: 2\n}\n"); + expect(PureBackend::renameKeySegments($src, ['obj', 'a.b'], 'new.name')) + ->toBe("obj: {\n \"new.name\": 1\n keep: 2\n}\n"); + }); + + it('renames block Object keys through their block anchor and rejects Array parents as unsupported', function () { + expect(PureBackend::renameKey("a: {\n x: 1\n}\n", 'a', 'b'))->toBe("b: {\n x: 1\n}\n"); + $caught = null; + try { PureBackend::renameKey("items: [x]\n", 'items.0', 'renamed'); } catch (KtavException $e) { $caught = $e; } + expect($caught)->toBeAnInstanceOf(KtavException::class); + expect($caught->getError())->toBe('EditUnsupported'); + }); + + it('preserves value and member order on rename and is byte-identical for same-key no-op', function () { + $src = "a: 1\nk:: +042\nb: 3\n"; + expect(PureBackend::renameKey($src, 'k', 'renamed'))->toBe("a: 1\nrenamed:: +042\nb: 3\n"); + expect(PureBackend::renameKey($src, 'k', 'k'))->toBe($src); + }); + + it('preserves ## comments for leaf edits and rejects destructive comment loss', function () { + $src = "a: {\n ## inner\n x: 1\n}\n"; + expect(PureBackend::renameKey($src, 'a.x', 'y'))->toBe("a: {\n ## inner\n y: 1\n}\n"); + $caught = null; + try { PureBackend::removeValue($src, 'a'); } catch (KtavException $e) { $caught = $e; } + expect($caught)->toBeAnInstanceOf(KtavException::class); + expect($caught->getError())->toBe('EditUnsupported'); + }); + + it('covers trailing commas, UTF-8, i64 values and lossless spellings', function () { + expect(PureBackend::loads("n: 9223372036854775807\n")['n'])->toBe(9223372036854775807); + expect(PureBackend::insertValue("a: {old: +01,}\n", 'a.new', 9223372036854775807)) + ->toBe("a: {old: +01, new: 9223372036854775807,}\n"); + expect(PureBackend::insertValue("a: {old: +01}\n", 'a.雪', 'café'))->toBe("a: {old: +01, 雪: café}\n"); + expect(PureBackend::renameKey("a: {old: +01,}\n", 'a.old', 'new'))->toBe("a: {new: +01,}\n"); + expect(PureBackend::removeValue("a: {old: +01,}\n", 'a.old'))->toBe("a: {}\n"); + $caught = null; + try { PureBackend::insertValue("a: {\n", 'a.new', 1); } catch (KtavException $e) { $caught = $e; } + expect($caught)->toBeAnInstanceOf(KtavException::class); + expect($caught->getError())->toBe('UnclosedCompound'); + $caught = null; + try { PureBackend::insertValue("a: \xE2\x82\n", 'a.new', 1); } catch (KtavException $e) { $caught = $e; } + expect($caught)->toBeAnInstanceOf(KtavException::class); + expect($caught->getError())->toBe('InvalidUtf8'); + expect($caught->getSpan())->toBe(['start' => 3, 'end' => 5]); + }); + + it('returns typed errors for collisions, missing targets and unsupported comment loss', function () { + $cases = [ + [static function () { PureBackend::insertValue("a: 1\n", 'a', 2); }, 'EditAlreadyExists'], + [static function () { PureBackend::removeValue("a: 1\n", 'missing'); }, 'EditNotFound'], + [static function () { PureBackend::renameKey("a: 1\n", 'missing', 'b'); }, 'EditNotFound'], + [static function () { PureBackend::renameKey("a: 1\nb: 2\n", 'a', 'b'); }, 'EditAlreadyExists'], + [static function () { PureBackend::removeValue("a: 1\n", ''); }, 'EditInvalidPath'], + [static function () { PureBackend::renameKey("a: 1\n", 'a', ''); }, 'EditUnsupported'], + ]; + foreach ($cases as $case) { + $caught = null; + try { $case[0](); } catch (KtavException $e) { $caught = $e; } + expect($caught)->toBeAnInstanceOf(KtavException::class); + expect($caught->getError())->toBe($case[1]); + } + }); +}); From 8ee9af10448e1fb56036233f29cec58e6f3f8678 Mon Sep 17 00:00:00 2001 From: Marat K Date: Tue, 27 Oct 2026 11:01:00 +0100 Subject: [PATCH 2/2] fix(edit): preserve transport preflight and UTF-8 parity Restore legacy replacement transport validation without requiring a native artifact, while keeping source-first validation for new mutation APIs. Normalize unsupported edit types to structured Message errors and match Rust UTF-8 wording without changing raw spans. Keep the documented PHP value mapping, correct invalid ArrayObject success fixtures and strengthen native/pure transport regressions. Co-Authored-By: Claude Opus 5.5 --- src/Ktav.php | 2 -- src/Pure/Edit/EditSplice.php | 42 +------------------------------- src/Pure/PureParser.php | 3 +-- src/Pure/PureScanner.php | 31 +++++++++++++++++++++++ src/WireJson.php | 17 ++++++++++++- tests/MutationNativeSpec.php | 38 ++++++++++++++++++++++++++--- tests/Pure/ErrorEnvelopeSpec.php | 32 ++++++++++++++++++++++++ tests/Pure/MutationSpec.php | 4 +-- 8 files changed, 117 insertions(+), 52 deletions(-) diff --git a/src/Ktav.php b/src/Ktav.php index 02a2799..8b80bae 100644 --- a/src/Ktav.php +++ b/src/Ktav.php @@ -169,7 +169,6 @@ public static function canonicalFromSource(string $src): string */ public static function editValue(string $source, string $path, $replacement): string { - self::validateEditSource($source); return NativeLib::callEditBytes( 'ktav_edit_value', $source, @@ -188,7 +187,6 @@ public static function editValue(string $source, string $path, $replacement): st */ public static function editValueSegments(string $source, array $segments, $replacement): string { - self::validateEditSource($source); // The segments transport is a JSON array of literal strings. // A json_encode failure is surfaced as a typed transport error // BEFORE any native call — the cause is never swallowed by a diff --git a/src/Pure/Edit/EditSplice.php b/src/Pure/Edit/EditSplice.php index 4ca5a13..56d56a8 100644 --- a/src/Pure/Edit/EditSplice.php +++ b/src/Pure/Edit/EditSplice.php @@ -245,47 +245,7 @@ public static function renameKeySegments(string $src, array $segments, string $n private static function utf8Error(string $value): string { - $span = PureScanner::validateUtf8($value); - $start = $span[0]; - $end = $span[1]; - $length = $end - $start; - $first = ord($value[$start]); - - // Rust's Utf8Error reports error_len as the number of bytes up to - // (but not including) the first byte that cannot continue the - // sequence. Only a genuinely truncated, still-valid prefix at EOF - // has error_len == None. Constrained second-byte failures (e.g. - // E0 80) are invalid immediately, even when EOF follows. - $expected = $first >= 0xC2 && $first <= 0xDF ? 2 - : ($first >= 0xE0 && $first <= 0xEF ? 3 - : ($first >= 0xF0 && $first <= 0xF4 ? 4 : 1)); - if ($expected === 1) { - // Illegal lead bytes are their own error, regardless of any - // continuation bytes that the scanner groups into its span. - $length = 1; - } elseif ($expected > 1) { - $validPrefix = 1; - while ($validPrefix < $expected && $start + $validPrefix < strlen($value)) { - $byte = ord($value[$start + $validPrefix]); - $position = $validPrefix; - $valid = $byte >= 0x80 && $byte <= 0xBF; - if ($position === 1 && $first === 0xE0) { $valid = $byte >= 0xA0 && $byte <= 0xBF; } - elseif ($position === 1 && $first === 0xED) { $valid = $byte >= 0x80 && $byte <= 0x9F; } - elseif ($position === 1 && $first === 0xF0) { $valid = $byte >= 0x90 && $byte <= 0xBF; } - elseif ($position === 1 && $first === 0xF4) { $valid = $byte >= 0x80 && $byte <= 0x8F; } - if (!$valid) { break; } - ++$validPrefix; - } - if ($start + $validPrefix === strlen($value) && $validPrefix < $expected) { - return 'incomplete utf-8 byte sequence from index ' . $start; - } - if ($validPrefix > 1) { - $length = $validPrefix; - } elseif ($length > 1 && $first >= 0xC2 && $first <= 0xF4) { - $length = 1; - } - } - return 'invalid utf-8 sequence of ' . $length . ' bytes from index ' . $start; + return PureScanner::utf8ErrorDisplay($value, PureScanner::validateUtf8($value)); } private static function validateMutationSegments(array $segments): void diff --git a/src/Pure/PureParser.php b/src/Pure/PureParser.php index f03e03d..a77abcb 100644 --- a/src/Pure/PureParser.php +++ b/src/Pure/PureParser.php @@ -90,8 +90,7 @@ public static function parse(string $src, bool $strict, ?array &$events = null, 'line' => $line, 'line_text' => null, 'span' => ['start' => $bad[0], 'end' => $bad[1]], - 'body' => 'input is not valid UTF-8: invalid utf-8 sequence of ' - . max(1, $bad[1] - $bad[0]) . ' byte(s) from index ' . $bad[0], + 'body' => 'input is not valid UTF-8: ' . PureScanner::utf8ErrorDisplay($src, $bad), 'message' => 'InvalidUtf8: input is not valid UTF-8; first invalid byte sequence at byte offset ' . $bad[0], ]); } diff --git a/src/Pure/PureScanner.php b/src/Pure/PureScanner.php index aad2b11..7cf8292 100644 --- a/src/Pure/PureScanner.php +++ b/src/Pure/PureScanner.php @@ -105,6 +105,37 @@ private static function invalidLeadSpan(string $s, int $start, int $end): array return [$start, $end]; } + /** Rust std::str::Utf8Error Display wording for the first error. */ + public static function utf8ErrorDisplay(string $s, array $span): string + { + $start = $span[0]; + $first = ord($s[$start]); + $expected = $first >= 0xC2 && $first <= 0xDF ? 2 + : ($first >= 0xE0 && $first <= 0xEF ? 3 + : ($first >= 0xF0 && $first <= 0xF4 ? 4 : 1)); + if ($expected === 1) { + $length = 1; + } else { + $validPrefix = 1; + $n = strlen($s); + while ($validPrefix < $expected && $start + $validPrefix < $n) { + $byte = ord($s[$start + $validPrefix]); + $valid = $byte >= 0x80 && $byte <= 0xBF; + if ($validPrefix === 1 && $first === 0xE0) { $valid = $byte >= 0xA0 && $byte <= 0xBF; } + elseif ($validPrefix === 1 && $first === 0xED) { $valid = $byte >= 0x80 && $byte <= 0x9F; } + elseif ($validPrefix === 1 && $first === 0xF0) { $valid = $byte >= 0x90 && $byte <= 0xBF; } + elseif ($validPrefix === 1 && $first === 0xF4) { $valid = $byte >= 0x80 && $byte <= 0x8F; } + if (!$valid) { break; } + ++$validPrefix; + } + if ($start + $validPrefix === strlen($s) && $validPrefix < $expected) { + return 'incomplete utf-8 byte sequence from index ' . $start; + } + $length = $validPrefix; + } + return 'invalid utf-8 sequence of ' . $length . ' bytes from index ' . $start; + } + /** * Byte length of the § 3.3 whitespace code point at $i (0 when not * whitespace). $inline excludes LF/CR (the line-bounded view). diff --git a/src/WireJson.php b/src/WireJson.php index 9f60686..90939f8 100644 --- a/src/WireJson.php +++ b/src/WireJson.php @@ -165,13 +165,28 @@ private static function wrap($v, bool $editObjects = false) 'path' => null, 'canonical' => null, 'spec_section' => null, - 'body' => null, + 'body' => 'edit replacement transport: only an EMPTY stdClass' + . ' (an explicit empty Object) is supported', 'message' => 'edit replacement transport: only an EMPTY stdClass' . ' (an explicit empty Object) is supported', ]); } return $v; // json_encode(new stdClass) === '{}' } + if ($editObjects) { + throw KtavException::fromEnvelope([ + 'error' => 'Message', + 'reason' => null, + 'line' => null, + 'line_text' => null, + 'span' => null, + 'path' => null, + 'canonical' => null, + 'spec_section' => null, + 'body' => 'edit replacement transport: unsupported PHP type ' . gettype($v), + 'message' => 'edit replacement transport: unsupported PHP type ' . gettype($v), + ]); + } throw new KtavException('unsupported value type for Ktav::dumps: ' . gettype($v)); } } diff --git a/tests/MutationNativeSpec.php b/tests/MutationNativeSpec.php index fab16ca..c6e84ba 100644 --- a/tests/MutationNativeSpec.php +++ b/tests/MutationNativeSpec.php @@ -345,22 +345,52 @@ function () use ($src) { return PureBackend::renameKeySegments($src, ['obj', 'a. ); }); - it('covers quoted inline members, escaped commas and ArrayObject mutation parity', function () use ($requireMutationAbi, $compareSuccess) { + it('covers quoted inline members, escaped commas and associative-array mutation parity', function () use ($requireMutationAbi, $compareSuccess) { $requireMutationAbi(); $compareSuccess( function () { return Ktav::insertValue("a: {x: 1}\n", 'a.k', 'p,q'); }, function () { return PureBackend::insertValue("a: {x: 1}\n", 'a.k', 'p,q'); }, "a: {x: 1, k: p\\,q}\n" ); - $arrayObject = new \ArrayObject(['x' => 1, 'y' => 2]); + $arrayValue = ['x' => 1, 'y' => 2]; $expected = "base: 0\nobj: {\n x: 1\n y: 2\n}\n"; $compareSuccess( - function () use ($arrayObject) { return Ktav::insertValue("base: 0\n", 'obj', $arrayObject); }, - function () use ($arrayObject) { return PureBackend::insertValue("base: 0\n", 'obj', $arrayObject); }, + function () use ($arrayValue) { return Ktav::insertValue("base: 0\n", 'obj', $arrayValue); }, + function () use ($arrayValue) { return PureBackend::insertValue("base: 0\n", 'obj', $arrayValue); }, $expected ); }); + it('matches Message bodies for nonempty stdClass edit values', function () use ($compareError) { + $bad = (object) ['x' => 1]; + $compareError( + function () use ($bad) { return Ktav::insertValue("base: 0\n", 'obj', $bad); }, + function () use ($bad) { return PureBackend::insertValue("base: 0\n", 'obj', $bad); }, + 'Message' + ); + }); + + it('rejects ArrayObject mutation values as typed messages without source fields', function () use ($requireMutationAbi) { + $requireMutationAbi(); + foreach ([ + function () { return Ktav::insertValue("base: 0\n", 'obj', new \ArrayObject(['x' => 1])); }, + function () { return PureBackend::insertValue("base: 0\n", 'obj', new \ArrayObject(['x' => 1])); }, + ] as $call) { + $error = null; + try { $call(); } catch (KtavException $e) { $error = $e; } + expect($error)->toBeAnInstanceOf(KtavException::class); + expect($error->getError())->toBe('Message'); + expect($error->getBody())->toBe('edit replacement transport: unsupported PHP type object'); + expect($error->getMessage())->toBe('edit replacement transport: unsupported PHP type object'); + expect($error->getErrorLine())->toBe(null); + expect($error->getSpan())->toBe(null); + expect($error->getPath())->toBe(null); + expect($error->getReason())->toBe(null); + expect($error->getLineText())->toBe(null); + expect($error->getCanonical())->toBe(null); + expect($error->getSpecSection())->toBe(null); + } + }); it('preserves trailing commas, UTF-8, i64 values and untouched source spelling', function () use ($requireMutationAbi, $compareSuccess, $compareError) { $requireMutationAbi(); $src = "a: {old: +01,}\n"; diff --git a/tests/Pure/ErrorEnvelopeSpec.php b/tests/Pure/ErrorEnvelopeSpec.php index f949387..fcff5ab 100644 --- a/tests/Pure/ErrorEnvelopeSpec.php +++ b/tests/Pure/ErrorEnvelopeSpec.php @@ -66,6 +66,38 @@ ); }); + it('matches the Rust invalid UTF-8 body while retaining its raw byte span', function () { + $thrown = null; + try { + PureBackend::loads("abc\xE2\x82A"); + } catch (KtavException $e) { + $thrown = $e; + } + + expect($thrown)->toBeAnInstanceOf(KtavException::class); + expect($thrown->getBody())->toBe('input is not valid UTF-8: invalid utf-8 sequence of 2 bytes from index 3'); + expect($thrown->getSpan())->toBe(['start' => 3, 'end' => 5]); + expect($thrown->getError())->toBe('InvalidUtf8'); + expect($thrown->getErrorLine())->toBe(1); + expect($thrown->getLineText())->toBeNull(); + }); + it('uses Rust Utf8Error Display independently of the raw span', function () { + $cases = [ + ["\xFF\x80", 'invalid utf-8 sequence of 1 bytes from index 0', [0, 2]], + ["\xE2\x82A", 'invalid utf-8 sequence of 2 bytes from index 0', [0, 2]], + ["\xF4\x90\x80\x80", 'invalid utf-8 sequence of 1 bytes from index 0', [0, 4]], + ["\xE2\x82", 'incomplete utf-8 byte sequence from index 0', [0, 2]], + ]; + foreach ($cases as [$source, $body, $span]) { + $thrown = null; + try { PureBackend::loads($source); } catch (KtavException $e) { $thrown = $e; } + expect($thrown)->toBeAnInstanceOf(KtavException::class); + expect($thrown->getBody())->toBe('input is not valid UTF-8: ' . $body); + expect($thrown->getSpan())->toBe(['start' => $span[0], 'end' => $span[1]]); + expect($thrown->getErrorLine())->toBe(1); + } + }); + it('invalid UTF-8 fails before grammar with a nonempty byte span', function () { $thrown = null; try { diff --git a/tests/Pure/MutationSpec.php b/tests/Pure/MutationSpec.php index 50b4924..e927a5d 100644 --- a/tests/Pure/MutationSpec.php +++ b/tests/Pure/MutationSpec.php @@ -39,8 +39,8 @@ ->toBe("## heading\nsettings: {old: +01, new: 2}\n## tail\n"); }); - it('handles ArrayObject values', function () { - expect(PureBackend::insertValue("base: 0\n", 'obj', new \ArrayObject(['x' => 1, 'y' => 2]))) + it('handles associative array values', function () { + expect(PureBackend::insertValue("base: 0\n", 'obj', ['x' => 1, 'y' => 2])) ->toBe("base: 0\nobj: {\n x: 1\n y: 2\n}\n"); });