Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
* text=auto eol=lf

# Polydoc требует пустую строку в конце промежуточных source parts.
root-docs/**/body-*.md whitespace=-blank-at-eof
*.bat text eol=crlf
*.cmd text eol=crlf
47 changes: 30 additions & 17 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -113,33 +113,46 @@ jobs:
ini-values: ffi.enable=1, xdebug.mode=off
coverage: xdebug

# Provenance (review3 #7, reworked review4): Cargo.lock is
# generated in CI, NOT committed. Generate it, then pin the
# published core with a real TOML parse (shell: bash — the matrix
# includes windows-latest): the ktav [[package]] entry must be
# exactly one, version 0.8.1, from the crates.io registry, with
# the published checksum. A local-path override, an unreleased
# branch or a swapped artifact fails the job here.
- name: Generate Cargo.lock and verify the published ktav 0.8.1 pin
# 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);
# 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)
shell: bash
run: |
set -e
cargo generate-lockfile
python3 - <<'PY'
import sys, tomllib
REV = '447a00bd012e8d3f347c7e1eb59c3f0d9a78332f'
with open('Cargo.lock', 'rb') as f:
data = tomllib.load(f)
pkgs = [p for p in data.get('package', []) if p.get('name') == 'ktav']
if len(pkgs) != 1:
sys.exit('expected exactly one ktav [[package]] entry, found %d' % len(pkgs))
p = pkgs[0]
if p.get('version') != '0.8.1':
sys.exit('ktav version %r != 0.8.1' % p.get('version'))
if p.get('source') != 'registry+https://github.com/rust-lang/crates.io-index':
sys.exit('ktav source %r is not the crates.io registry' % p.get('source'))
if p.get('checksum') != '7140dfe2fa6c320e74768cd6a637828c2d26f81746254f4fcd805f3993bd3fd5':
sys.exit('ktav checksum %r mismatch' % p.get('checksum'))
print('ktav 0.8.1 provenance verified:', p['source'])
src = p.get('source', '')
if src != 'git+https://github.com/ktav-lang/rust?rev=' + REV + '#' + REV or p.get('version') != '0.9.0':
sys.exit('ktav source %r is not the ktav-lang/rust git pin' % src)
if REV not in src:
sys.exit('ktav git source %r does not pin the immutable rev %s' % (src, REV))
if 'registry+' in src or 'path+' in src:
sys.exit('ktav source %r is a registry or local-path dependency' % src)
print('ktav immutable git-core pin verified:', src)
PY
# ABI gate: the pinned core must export the ABI-2 set before
# any PHP native cell runs.
python3 - <<'PY'
import sys, tomllib
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,))
print('workspace ktav dependency pinned:', ktav['rev'])
PY

- name: Build native library
Expand Down Expand Up @@ -410,8 +423,8 @@ jobs:
KTAV_LIB_PATH: ${{ github.workspace }}/target/debug/libktav_cabi.so
run: vendor/bin/kahlan --spec=tests/NativeDebugEmptySpec.php --reporter=verbose

- name: Assert the loaded native reports 0.8.1
- name: Assert the loaded native serves calls through the ABI-2 gate
env:
KTAV_LIB_PATH: ${{ github.workspace }}/target/debug/libktav_cabi.so
run: |
php -r "require 'vendor/autoload.php'; exit(\\Ktav\\Ktav::nativeVersion() === '0.8.1' ? 0 : 1);"
php -r "require 'vendor/autoload.php'; if (\Ktav\Ktav::nativeVersion() === '') { exit(1); } if (\Ktav\NativeLib::EXPECTED_ABI_VERSION !== 2) { exit(1); } exit(0);"
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,12 @@ This changelog tracks **binding releases**, not changes to the Ktav format
itself — for the latter see
[`ktav-lang/spec`](https://github.com/ktav-lang/spec/blob/main/CHANGELOG.md).

## Unreleased — 0.9 preparation

- Add native and standalone pure editing by textual path or literal segments: source splicing, preserved container forms, minimal readability transitions, comment protection, byte-identical no-op and semantic verification.
- Apply 0.9 source diagnostics and the pinned 412-case conformance corpus, including 72 diagnostic fixtures with raw UTF-8 byte locations and EOF opener spans.
- Native uses the immutable preparing-0.9 core and C ABI 2; pure remains independent of native binaries. Package versions are unchanged; this functionality is not published in 0.8.1.

## Unreleased

### 0.8.1
Expand Down
4 changes: 2 additions & 2 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ repository = "https://github.com/ktav-lang/php"
rust-version = "1.71"

[workspace.dependencies]
# Minimum core version; CI verifies the resolved release artifact separately.
ktav = ">=0.8.1, <0.9"
# Подготовка 0.9: immutable core pin с source-edit и ABI 2; пакет ещё не опубликован.
ktav = { git = "https://github.com/ktav-lang/rust", rev = "447a00bd012e8d3f347c7e1eb59c3f0d9a78332f" }
serde = { version = "1", features = ["derive"] }
serde_json = { version = "1", features = ["preserve_order"] }
indexmap = "2"
Expand Down
35 changes: 35 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,8 @@ $text = Ktav::dumps($doc);

A complete runnable example lives in [`examples/basic.php`](examples/basic.php).

> **Unreleased (0.9 preparation):** These editing APIs and updated diagnostics are not included in published 0.8.1 packages. Native backends require the pinned 0.9 core (C ABI 2 for C-FFI); pure backends remain standalone.

## API

| Method | Purpose |
Expand Down Expand Up @@ -142,6 +144,39 @@ Documented differences:
- Pure mode needs enabled standard `ext-json`, but no third-party
runtime Composer packages, FFI or native binary.

Source editing (spec 0.9). `editValue($source, $path, $replacement)`
and `editValueSegments($source, $segments, $replacement)` replace an
EXISTING value in the source text and return the new text; the input
is never mutated. Only the bytes of the target (and of inline wrappers
the layout rules force to expand) change: comments, key spelling and
order, dotted/inline/block forms, BOM, CR/LF/CRLF and the final-EOL
state survive; a no-op is byte-identical even for noncanonical
spelling. The textual path `key1.key2.0.key4` uses `.` as the
separator, `\.` for a literal dot and `\\` for a literal backslash;
segments are already-decoded literal names. Errors are distinct
envelope codes: `EditInvalidPath` (body = UTF-8 byte offset in the
path), `EditNotFound` (missing key, out-of-bounds index, scalar
descent, empty path) and `EditUnsupported` (noncontiguous
dotted/reopen targets, structural replacement of a comment-carrying
container, a replacement String containing CR or a line `))`). A
source that does not parse raises the ordinary parser envelope. On the
native side these methods require a `ktav_cabi` exporting the
source-edit ABI (version 2); an older binary fails with a clear
version error and is never replaced by a hidden pure fallback. A PHP
empty array as the replacement follows the nested empty-LIST
convention; an EMPTY `stdClass` is the explicit empty Object (`[]`
cannot express it), a NON-empty `stdClass` is a `Message` transport
failure; typed payloads (`['$i' => …]`, `['$f' => …]`) go through
the same strict wire ingest as the native codec — `$i` is canonicalized
(explicit `+` stripped, redundant leading zeros trimmed, signed zero
normalized to `0`, bignums digit-exact), `$f` must be a decimal lexical
form re-emitted shortest round-trip, and any invalid payload is a
`Message` transport failure, never a coerced scalar. Integer identity
is exact digit-string equality and Float identity is exact f64 equality
(the sign of zero is preserved, never a `precision`-ini string cast);
Object equality IGNORES key order (Rust IndexMap PartialEq), arrays
stay ordered.

### Formatting

`Ktav::format()` takes Ktav **source text** and returns Ktav source
Expand Down
6 changes: 6 additions & 0 deletions docs/ru/CHANGELOG.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,12 @@ MINOR — ломающий.
формата Ktav — для последнего см.
[`ktav-lang/spec`](https://github.com/ktav-lang/spec/blob/main/CHANGELOG.md).

## Ещё не выпущено — подготовка 0.9

- Добавлено редактирование по текстовому пути или буквальным сегментам в native- и самостоятельном pure-backend: source splice, сохранение форм контейнеров, минимальные переходы читаемости, защита комментариев, byte-identical no-op и семантическая проверка.
- Применена диагностика исходника 0.9 и закреплён corpus из 412 фикстур, включая 72 диагностические фикстуры с позициями сырых байтов UTF-8 и EOF spans от opener.
- Native использует immutable ядро подготовки 0.9 и C ABI 2; pure не требует native-бинарников. Версии пакетов не менялись; функционал не опубликован в 0.8.1.

## Unreleased

### 0.8.1
Expand Down
36 changes: 36 additions & 0 deletions docs/ru/README.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,8 @@ $text = Ktav::dumps($doc);

Полный запускаемый пример — в [`examples/basic.php`](../../examples/basic.php).

> **Ещё не выпущено (подготовка 0.9):** Эти API редактирования и обновлённая диагностика не входят в опубликованные пакеты 0.8.1. Native-backend требует закреплённое ядро 0.9 (C ABI 2 для C-FFI); pure-backend остаётся самостоятельным.

## API

| Метод | Назначение |
Expand Down Expand Up @@ -143,6 +145,40 @@ Object, последовательные массивы — Array. Для бол
- Чистому режиму нужно включённое стандартное `ext-json`, но не
сторонние runtime-зависимости Composer, FFI или нативный бинарник.

Правка исходника (spec 0.9). `editValue($source, $path, $replacement)`
и `editValueSegments($source, $segments, $replacement)` заменяют
СУЩЕСТВУЮЩЕЕ значение в тексте исходника и возвращают новую строку;
вход не мутируется. Меняются только байты цели (и inline-обёрток,
которые требует раскрыть правило компоновки): комментарии, написание
и порядок ключей, формы dotted/inline/block, BOM, CR/LF/CRLF и наличие
финального EOL сохраняются; no-op байт-в-байт идентичен исходнику,
даже при неканоничном написании. Текстовый путь `key1.key2.0.key4`
использует `.` как разделитель, `\.` для literal точки и `\\` для
literal обратного слеша; сегменты — уже декодированные literal имена.
Ошибки — отдельные коды конверта: `EditInvalidPath` (body = UTF-8
смещение в пути), `EditNotFound` (нет ключа, индекс вне диапазона,
спуск через скаляр, пустой путь) и `EditUnsupported`
(неконтiguous dotted/reopen-цели, структурная замена контейнера с
комментариями, строка замены с CR или строкой `))`). Исходник с
ошибкой разбора даёт обычный конверт парсера. На нативной стороне эти
методы требуют `ktav_cabi` с ABI правки исходника (версия 2); старый
бинарник отклоняется с понятной ошибкой версии и никогда не
подменяется скрытым pure-fallback. Пустой PHP-массив в качестве
замены следует соглашению вложенного пустого LIST; ПУСТОЙ `stdClass` —
это явный пустой Object (`[]` его не выражает), НЕпустой `stdClass` —
транспортный сбой `Message`; типизированные
полезные нагрузки (`['$i' => …]`, `['$f' => …]`) проходят тот же
строгий wire-ingest, что и нативный кодек — `$i` канонизируется
(явный `+` снимается, лишние ведущие нули срезаются, знаковый нуль
нормализуется к `0`, бигнумы точны по цифрам), `$f` обязана быть
десятичной лексической формой и переиспускается в кратчайшей форме,
любой невалидный payload — транспортный сбой `Message`, а не
принудительно приведённый скаляр. Идентичность Integer — точное
сравнение строк цифр, Float — точное сравнение f64 (знак нуля
сохраняется, без строкового каста через `precision`); равенство
Object ИГНОРИРУЕТ порядок ключей (Rust IndexMap PartialEq), массивы
остаются упорядоченными.

### Форматирование

`Ktav::format()` принимает Ktav-**исходник** и возвращает Ktav-исходник.
Expand Down
6 changes: 6 additions & 0 deletions docs/zh/CHANGELOG.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,12 @@ MINOR 递增即破坏性变更。
后者见
[`ktav-lang/spec`](https://github.com/ktav-lang/spec/blob/main/CHANGELOG.md)。

## 尚未发布 — 0.9 准备版本

- 新增原生及独立纯实现的路径编辑,支持点分文本或字面路径段:源文本拼接、保留容器形式、最小可读性展开、注释保护、逐字节 no-op 及语义验证。
- 应用 0.9 源诊断及固定的 412 个一致性 fixture,包括 72 个诊断 fixture,检查原始 UTF-8 字节位置及从起始标记到 EOF 的区间。
- 原生后端使用不可变的 0.9 准备核心及 C ABI 2;纯实现不需要原生二进制。包版本不变,这些功能尚未包含在已发布的 0.8.1 中。

## Unreleased

### 0.8.1
Expand Down
25 changes: 25 additions & 0 deletions docs/zh/README.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,8 @@ $text = Ktav::dumps($doc);

完整可运行示例见 [`examples/basic.php`](../../examples/basic.php)。

> **尚未发布(0.9 准备版本):** 这些编辑 API 和更新后的诊断不包含在已发布的 0.8.1 包中。原生后端需要固定的 0.9 核心(C-FFI 使用 C ABI 2);纯实现仍完全独立。

## API

| 方法 | 用途 |
Expand Down Expand Up @@ -139,6 +141,29 @@ FFI,选择原生模式也不会执行 PHP 解析。
- 纯模式需要启用标准 `ext-json`,但无需第三方 Composer 运行时依赖、
FFI 或原生二进制。

源码编辑(spec 0.9)。`editValue($source, $path, $replacement)` 和
`editValueSegments($source, $segments, $replacement)` 会替换源文本中的
已有值并返回新文本;输入不会被修改。只有目标字节(以及布局规则要求
展开的 inline 包装)会改变:注释、键的拼写与顺序、dotted/inline/block
形式、BOM、CR/LF/CRLF 和末尾 EOL 状态都会保留;即使源码拼写非规范,
no-op 结果也与源码逐字节相同。文本路径 `key1.key2.0.key4` 以 `.` 为
分隔符,`\.` 表示字面点号,`\\` 表示字面反斜杠;segments 是已解码的
字面名称。错误是不同的信封代码:`EditInvalidPath`(body = 路径中的
UTF-8 字节偏移)、`EditNotFound`(键缺失、索引越界、穿过标量、空
路径)和 `EditUnsupported`(dotted/reopen 的非连续目标、对含注释
容器的结构性替换、包含 CR 或行 `))` 的替换字符串)。源码解析失败会
抛出普通的解析器信封。原生侧这些方法需要导出源码编辑 ABI(版本 2)
的 `ktav_cabi`;旧二进制会以明确的版本错误被拒绝,绝不会静默退化为
纯 PHP 后备。空 PHP 数组作为替换值遵循嵌套空 LIST 约定;空的 `stdClass` 表示显式的空
Object(`[]` 无法表达),非空 `stdClass` 是 `Message` 传输失败;类型化载荷
(`['$i' => …]`、`['$f' => …]`)经过与原生编解码器相同的严格 wire-ingest
—— `$i` 会规范化(去掉显式 `+`、裁剪多余的先导零、带符号零归一化为
`0`、大数按位精确),`$f` 必须是十进制词法形式并按最短往返形式重新
输出;任何无效载荷都是 `Message` 传输失败,绝不会被强转成标量。
Integer 身份是精确的数字串比较,Float 身份是精确的 f64 比较(保留零
的符号,不经过 `precision` 的字符串转换);Object 相等会忽略键顺序
(Rust IndexMap PartialEq),数组保持有序。

### 格式化

`Ktav::format()` 接受 Ktav **源文本**,并返回 Ktav 源文本。
Expand Down
1 change: 1 addition & 0 deletions root-docs/CHANGELOG/manifest.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
export default [
"preamble",
"source-edit09",
"unreleased",
"v0-8-0",
"v0-6-4",
Expand Down
21 changes: 21 additions & 0 deletions root-docs/CHANGELOG/source-edit09/body-1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
>>>>> lang=en
## Unreleased — 0.9 preparation

- Add native and standalone pure editing by textual path or literal segments: source splicing, preserved container forms, minimal readability transitions, comment protection, byte-identical no-op and semantic verification.
- Apply 0.9 source diagnostics and the pinned 412-case conformance corpus, including 72 diagnostic fixtures with raw UTF-8 byte locations and EOF opener spans.
- Native uses the immutable preparing-0.9 core and C ABI 2; pure remains independent of native binaries. Package versions are unchanged; this functionality is not published in 0.8.1.

>>>>> lang=ru
## Ещё не выпущено — подготовка 0.9

- Добавлено редактирование по текстовому пути или буквальным сегментам в native- и самостоятельном pure-backend: source splice, сохранение форм контейнеров, минимальные переходы читаемости, защита комментариев, byte-identical no-op и семантическая проверка.
- Применена диагностика исходника 0.9 и закреплён corpus из 412 фикстур, включая 72 диагностические фикстуры с позициями сырых байтов UTF-8 и EOF spans от opener.
- Native использует immutable ядро подготовки 0.9 и C ABI 2; pure не требует native-бинарников. Версии пакетов не менялись; функционал не опубликован в 0.8.1.

>>>>> lang=zh
## 尚未发布 — 0.9 准备版本

- 新增原生及独立纯实现的路径编辑,支持点分文本或字面路径段:源文本拼接、保留容器形式、最小可读性展开、注释保护、逐字节 no-op 及语义验证。
- 应用 0.9 源诊断及固定的 412 个一致性 fixture,包括 72 个诊断 fixture,检查原始 UTF-8 字节位置及从起始标记到 EOF 的区间。
- 原生后端使用不可变的 0.9 准备核心及 C ABI 2;纯实现不需要原生二进制。包版本不变,这些功能尚未包含在已发布的 0.8.1 中。

7 changes: 7 additions & 0 deletions root-docs/CHANGELOG/source-edit09/meta.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
export default {
"kind": "frontmatter",
"number": null,
"level": null,
"title": null,
"bodyParts": 1
}
Loading
Loading