tree-sitter-ktav 0.6.1 → 0.8.0

package/README.md

@@ -19,9 +19,10 @@
 ## What is Ktav?
 
 Ktav (Hebrew **כְּתָב**, "writing") is a plain-text configuration
-format. JSON-shape (scalars, arrays, objects, `null`, booleans), but
-without quotes around strings, without commas, and with dotted keys
-(`server.port: 8080`) for nesting. The full specification — the same
+format with a JSON-shaped data model (scalars, arrays, objects, `null`,
+booleans). Strings are unquoted, ordinary entries have no commas (inline
+compounds use commas), and dotted keys (`server.port: 8080`) express
+nesting. The full specification — the same
 one all official Ktav implementations target — lives in the
 [`ktav-lang/spec`](https://github.com/ktav-lang/spec) repository.
 
@@ -41,7 +42,7 @@ this crate / npm package is the one for Ktav.
 ```toml
 [dependencies]
 tree-sitter         = "0.25"
-tree-sitter-ktav    = "0.6.0"
+tree-sitter-ktav    = "0.8.0"
 ```
 
 ```rust
@@ -58,6 +59,10 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 
 ### Node.js (`tree-sitter` package)
 
+The npm package ships native source, not prebuilt `.node` binaries.
+Installation needs a C/C++ build toolchain and Python for `node-gyp`;
+the generated parser is included, so the Tree-sitter CLI is not needed.
+
 ```bash
 npm install tree-sitter tree-sitter-ktav
 ```
@@ -77,25 +82,33 @@ console.log(tree.rootNode.toString());
 
 ### Neovim (with [`nvim-treesitter`](https://github.com/nvim-treesitter/nvim-treesitter))
 
-Until the grammar is upstreamed, register it manually in your config:
+The current `nvim-treesitter` main branch no longer uses the legacy
+`get_parser_configs()` registration API. Build the parser library from the
+grammar repository, then load it with Neovim's Tree-sitter API. The CLI
+includes `src/scanner.c` automatically when building this grammar:
 
 ```lua
-require("nvim-treesitter.parsers").get_parser_configs().ktav = {
-  install_info = {
-    url = "https://github.com/ktav-lang/tree-sitter-ktav",
-    files = { "src/parser.c" },
-    branch = "main",
-  },
-  filetype = "ktav",
-}
-
+require("nvim-treesitter").setup({})
 vim.filetype.add({ extension = { ktav = "ktav" } })
+vim.treesitter.language.add("ktav", {
+  path = vim.fn.stdpath("data") .. "/site/parser/ktav.so",
+})
+vim.api.nvim_create_autocmd("FileType", {
+  pattern = "ktav",
+  callback = function() vim.treesitter.start() end,
+})
 ```
 
-Then `:TSInstall ktav`. Drop `queries/highlights.scm`,
-`queries/locals.scm`, and `queries/injections.scm` into your
-`~/.config/nvim/queries/ktav/` directory (or let nvim-treesitter pick
-them up from the parser repo).
+Create the target `parser` directory first. On Unix, for example, run
+`mkdir -p ~/.local/share/nvim/site/parser`, then build from the grammar
+repository with `npx tree-sitter build --output
+~/.local/share/nvim/site/parser/ktav.so`. The directory and `.so` filename
+are Unix examples; use the path from `stdpath("data")` and your platform's
+shared-library extension (for example, `.dll` on Windows) in both the build
+command and Lua config. If building from an explicit source-file list,
+include both `src/parser.c` and `src/scanner.c`. Copy
+`queries/highlights.scm`, `queries/locals.scm`, and `queries/injections.scm`
+to `~/.config/nvim/queries/ktav/`.
 
 ### Helix
 
@@ -107,7 +120,7 @@ name      = "ktav"
 scope     = "source.ktav"
 file-types = ["ktav"]
 roots     = []
-comment-token = "#"
+comment-token = "##"
 indent    = { tab-width = 4, unit = "    " }
 
 [[grammar]]
@@ -125,38 +138,47 @@ with tree-sitter support can consume it once the parser is built.
 
 ## Node types
 
-The grammar produces the following named nodes:
+Representative named nodes from the CST (`src/node-types.json`) include:
 
 | Node                       | What it captures                                |
 |----------------------------|-------------------------------------------------|
 | `source_file`              | the whole document                              |
-| `comment`                  | a `#`-line comment                              |
+| `comment`                  | a `##`-line comment                             |
 | `blank_line`               | an empty line                                   |
 | `object_pair`              | `key SEP value` line                            |
-| `key` / `dotted_key`       | the key portion (with optional `.` separators)  |
-| `sep_string` / `sep_raw` / `sep_int` / `sep_float` | the four separators       |
-| `keyword` / `kw_null` / `kw_true` / `kw_false`     | keywords                  |
-| `scalar`                   | the catch-all single-line value body            |
+| `key` / `dotted_key`       | the key portion and dotted segments             |
+| `quoted_key_segment`       | a `"…"`, `'…'` or `` `…` `` key segment (§ 5.3.3) |
+| `escape_sequence`          | an escape in a key or inline value (§ 3.7)      |
+| `sep_string` / `sep_raw`   | the `:` and `::` pair separators                |
+| `keyword` / `kw_null` / `kw_true` / `kw_false`     | keywords, whole-line and inline |
+| `integer` / `float`        | numbers, whole-line and inline (§ 5.2 typing)  |
+| `scalar` / `raw_scalar`    | ordinary and raw single-line values             |
+| `top_scalar`               | a string item of a root-level Array             |
+| `inline_scalar` / `inline_raw_scalar` | string values after `:` / `::` in inline compounds |
 | `compound_object`          | `{` … `}` block                                 |
 | `compound_array`           | `[` … `]` block                                 |
-| `array_item`               | a single item in an array                       |
+| `inline_object` / `inline_array` | inline compounds with comma-separated entries |
+| `inline_pair` / `inline_value` | entries and values in inline compounds        |
+| `array_item` / `top_array_item` | items in compound and top-level arrays         |
 | `multiline_stripped`       | `(` … `)` block                                 |
 | `multiline_verbatim`       | `((` … `))` block                               |
 | `multiline_content_line`   | a single line inside a multi-line string        |
 | `empty_object` / `empty_array` / `empty_paren` / `empty_double_paren` | inline empty forms |
-| `empty_value`              | separator immediately followed by EOL           |
+| `empty_value`              | separator plus the maximal allowed whitespace run through EOL or true EOF |
 
-`object_pair` exposes `key`, `separator`, and `value` as fields;
-`array_item` exposes `marker` (optional) and `value`.
+`object_pair` and `inline_pair` expose `key`, `separator`, and `value` fields
+(`inline_pair.value` is optional); `array_item` and `top_array_item` expose a
+required `value` and optional `marker`.
 
 ## Building from source
 
 ```bash
-git clone https://github.com/ktav-lang/tree-sitter-ktav.git
+git clone --recurse-submodules https://github.com/ktav-lang/tree-sitter-ktav.git
 cd tree-sitter-ktav
-npm install
-npx tree-sitter generate     # writes src/parser.c
-npx tree-sitter test         # runs the corpus
+npm ci                       # installs the locked tree-sitter-cli 0.26.8
+npx tree-sitter generate     # regenerates src/parser.c and related files
+npx tree-sitter test         # runs the tree-sitter corpus
+cargo test                   # Rust tests, including spec conformance
 ```
 
 The generated `src/parser.c`, `src/grammar.json`, `src/node-types.json`,
@@ -165,13 +187,14 @@ so consumers do not need the CLI to build.
 
 ## Status
 
-`0.6.0` — implements [Ktav 0.6.0](https://github.com/ktav-lang/spec/blob/main/versions/0.6/spec.md).
-The grammar accepts every valid Ktav 0.6.0 document (verified against
-all `tests/valid/*.ktav` fixtures from the spec repo). It is a
-syntactic accepter, not a strict spec validator — see
-[`CHANGELOG.md`](CHANGELOG.md) "Known limitations" for the small
-number of pathological cases the grammar accepts that the spec
-rejects (mostly missing-whitespace-after-marker — § 6.10).
+`0.8.0` — Tree-sitter grammar targeting the syntax in [Ktav 0.8.0](https://github.com/ktav-lang/spec/blob/main/versions/0.8/spec.md).
+The grammar parses every pinned spec 0.8 valid fixture without error and
+checks each Object/Array root against its JSON oracle. Every invalid
+fixture yields a syntax error except those needing key validation
+(`DuplicateKey`, `KeyPathConflict`) or pre-parse UTF-8 byte validation
+(`InvalidUtf8`). Tree-sitter supplies
+editor syntax trees; it does not perform the semantic validation of the
+reference Rust parser.
 
 ## License
 

package/README.ru.md

@@ -1,10 +1,10 @@
 # tree-sitter-ktav
 
 > Грамматика [tree-sitter](https://tree-sitter.github.io/) для
-> [Ktav (כְּתָב)](https://github.com/ktav-lang/spec) — Written
-> Configuration Format.
+> [Ktav (כְּתָב)](https://github.com/ktav-lang/spec) — формата
+> письменной конфигурации.
 
-**Языки:** [English](README.md) · **Русский** · [简体中文](README.zh.md)
+**Languages:** [English](README.md) · **Русский** · [简体中文](README.zh.md)
 
 **Песочница:** конвертация JSON / YAML / TOML / INI ⇄ Ktav прямо в браузере — **[ktav-lang.github.io](https://ktav-lang.github.io/)**.
 
@@ -20,8 +20,9 @@
 
 Ktav (иврит **כְּתָב**, «писание») — текстовый формат конфигурации
 JSON-формы (скаляры, массивы, объекты, `null`, булево), но без кавычек
-вокруг строк, без запятых, с точечными ключами (`server.port: 8080`)
-для вложенности. Полная спецификация (та же, на которую ориентируются
+вокруг строк; между обычными элементами запятых нет, однако в inline-
+структурах они используются. Для вложенности служат точечные ключи
+(`server.port: 8080`). Полная спецификация (та же, на которую ориентируются
 все официальные реализации Ktav) лежит в
 [`ktav-lang/spec`](https://github.com/ktav-lang/spec).
 
@@ -36,12 +37,12 @@ VS Code, Zed, …) используют его для подсветки син
 
 ## Установка
 
-### Rust
+### Rust (крейт `tree-sitter`)
 
 ```toml
 [dependencies]
-tree-sitter      = "0.25"
-tree-sitter-ktav = "0.6.0"
+tree-sitter         = "0.25"
+tree-sitter-ktav    = "0.8.0"
 ```
 
 ```rust
@@ -56,7 +57,11 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
-### Node.js
+### Node.js (пакет `tree-sitter`)
+
+Пакет npm содержит исходники нативного модуля, а не готовые `.node`-бинарники.
+Для установки нужны компилятор C/C++ и Python для `node-gyp`;
+сгенерированный парсер уже включён, поэтому Tree-sitter CLI не нужен.
 
 ```bash
 npm install tree-sitter tree-sitter-ktav
@@ -75,27 +80,35 @@ console.log(tree.rootNode.toString());
 
 ## Интеграция с редакторами
 
-### Neovim (через [`nvim-treesitter`](https://github.com/nvim-treesitter/nvim-treesitter))
+### Neovim (с [`nvim-treesitter`](https://github.com/nvim-treesitter/nvim-treesitter))
 
-Пока грамматика не зарегистрирована в апстриме, добавьте вручную:
+В текущей основной ветке `nvim-treesitter` больше не используется устаревший
+API регистрации `get_parser_configs()`. Соберите библиотеку парсера из
+репозитория грамматики и загрузите её через Tree-sitter API Neovim. CLI
+автоматически включает `src/scanner.c` при сборке этой грамматики:
 
 ```lua
-require("nvim-treesitter.parsers").get_parser_configs().ktav = {
-  install_info = {
-    url = "https://github.com/ktav-lang/tree-sitter-ktav",
-    files = { "src/parser.c" },
-    branch = "main",
-  },
-  filetype = "ktav",
-}
-
+require("nvim-treesitter").setup({})
 vim.filetype.add({ extension = { ktav = "ktav" } })
+vim.treesitter.language.add("ktav", {
+  path = vim.fn.stdpath("data") .. "/site/parser/ktav.so",
+})
+vim.api.nvim_create_autocmd("FileType", {
+  pattern = "ktav",
+  callback = function() vim.treesitter.start() end,
+})
 ```
 
-Затем `:TSInstall ktav`. Положите `queries/highlights.scm`,
-`queries/locals.scm` и `queries/injections.scm` в
-`~/.config/nvim/queries/ktav/` (либо позвольте `nvim-treesitter`
-подобрать их из репозитория грамматики).
+Сначала создайте целевой каталог `parser`. Например, в Unix выполните
+`mkdir -p ~/.local/share/nvim/site/parser`, затем из репозитория грамматики
+соберите библиотеку командой `npx tree-sitter build --output
+~/.local/share/nvim/site/parser/ktav.so`. Каталог и расширение `.so` здесь
+приведены как пример для Unix; используйте путь из `stdpath("data")` и
+расширение динамической библиотеки вашей платформы (например, `.dll` в
+Windows) и в команде сборки, и в Lua-конфигурации. Если список исходников
+задаётся явно, включите `src/parser.c` и `src/scanner.c`. Скопируйте
+`queries/highlights.scm`, `queries/locals.scm` и `queries/injections.scm` в
+`~/.config/nvim/queries/ktav/`.
 
 ### Helix
 
@@ -107,7 +120,7 @@ name      = "ktav"
 scope     = "source.ktav"
 file-types = ["ktav"]
 roots     = []
-comment-token = "#"
+comment-token = "##"
 indent    = { tab-width = 4, unit = "    " }
 
 [[grammar]]
@@ -123,40 +136,49 @@ source = { git = "https://github.com/ktav-lang/tree-sitter-ktav", rev = "main" }
 (`src/node-types.json`) и запросы (`queries/*.scm`), так что любой
 редактор с поддержкой tree-sitter сможет с ней работать.
 
-## Узлы AST
+## Типы узлов CST
 
-Грамматика генерирует следующие именованные узлы:
+Примеры именованных узлов CST (см. `src/node-types.json`):
 
 | Узел                       | Что захватывает                                  |
 |----------------------------|--------------------------------------------------|
 | `source_file`              | весь документ                                    |
-| `comment`                  | строковый комментарий `#`                        |
+| `comment`                  | строковый комментарий `##`                       |
 | `blank_line`               | пустую строку                                    |
 | `object_pair`              | строку `ключ SEP значение`                       |
-| `key` / `dotted_key`       | ключ (с возможным `.`-разбиением)                |
-| `sep_string` / `sep_raw` / `sep_int` / `sep_float` | четыре разделителя           |
-| `keyword` / `kw_null` / `kw_true` / `kw_false`     | ключевые слова               |
-| `scalar`                   | универсальное однострочное значение              |
+| `key` / `dotted_key`       | ключ и сегменты точечного пути                   |
+| `quoted_key_segment`       | сегмент ключа `"…"`, `'…'` или `` `…` `` (§ 5.3.3) |
+| `escape_sequence`          | экранирование в ключе или inline-значении (§ 3.7) |
+| `sep_string` / `sep_raw`   | разделители пар `:` и `::`                       |
+| `keyword` / `kw_null` / `kw_true` / `kw_false`     | ключевые слова, в строке и inline |
+| `integer` / `float`        | числа, в строке и inline (типизация § 5.2)       |
+| `scalar` / `raw_scalar`    | обычные и raw-значения в одну строку              |
+| `top_scalar`               | строковый элемент массива верхнего уровня        |
+| `inline_scalar` / `inline_raw_scalar` | строковые значения после `:` / `::` в inline-структурах |
 | `compound_object`          | блок `{` … `}`                                   |
 | `compound_array`           | блок `[` … `]`                                   |
-| `array_item`               | элемент массива                                  |
+| `inline_object` / `inline_array` | inline-структуры с элементами через запятую |
+| `inline_pair` / `inline_value` | пары и значения inline-структур              |
+| `array_item` / `top_array_item` | элементы массива и массива верхнего уровня    |
 | `multiline_stripped`       | блок `(` … `)`                                   |
 | `multiline_verbatim`       | блок `((` … `))`                                 |
 | `multiline_content_line`   | строка внутри многострочного значения            |
 | `empty_object` / `empty_array` / `empty_paren` / `empty_double_paren` | пустые inline-формы |
-| `empty_value`              | разделитель сразу за концом строки               |
+| `empty_value`              | разделитель и максимальная последовательность допустимых пробелов до конца строки или файла |
 
-`object_pair` экспонирует поля `key`, `separator`, `value`;
-`array_item` — `marker` (опционально) и `value`.
+`object_pair` и `inline_pair` имеют поля `key`, `separator`, `value`
+(`inline_pair.value` необязательно); `array_item` и `top_array_item` имеют
+обязательное `value` и необязательное `marker`.
 
 ## Сборка из исходников
 
 ```bash
-git clone https://github.com/ktav-lang/tree-sitter-ktav.git
+git clone --recurse-submodules https://github.com/ktav-lang/tree-sitter-ktav.git
 cd tree-sitter-ktav
-npm install
-npx tree-sitter generate     # генерирует src/parser.c
-npx tree-sitter test         # запускает корпус
+npm ci                       # устанавливает tree-sitter-cli 0.26.8 из lock-файла
+npx tree-sitter generate     # обновляет src/parser.c и связанные файлы
+npx tree-sitter test         # запускает корпус tree-sitter
+cargo test                   # тесты Rust, включая проверку соответствия спекам
 ```
 
 Файлы `src/parser.c`, `src/grammar.json`, `src/node-types.json` и
@@ -165,17 +187,19 @@ npx tree-sitter test         # запускает корпус
 
 ## Статус
 
-`0.6.0` — реализует [Ktav 0.6.0](https://github.com/ktav-lang/spec/blob/main/versions/0.6/spec.md).
-Грамматика принимает любой валидный документ Ktav 0.6.0 (проверено на
-всех фикстурах `tests/valid/*.ktav` из spec-репозитория). Это
-синтаксический акцептор, а не строгий валидатор — небольшое число
-патологических случаев, которые грамматика принимает, а спецификация
-запрещает (в основном § 6.10, отсутствие пробела после маркера),
-перечислены в [`CHANGELOG.md`](CHANGELOG.md).
+`0.8.0` — Tree-sitter-грамматика синтаксиса [Ktav 0.8.0](https://github.com/ktav-lang/spec/blob/main/versions/0.8/spec.md).
+Грамматика разбирает все закреплённые валидные фикстуры spec 0.8 без
+ошибок и сверяет корневой Object/Array с JSON-оракулом. Каждая
+невалидная фикстура даёт синтаксическую ошибку, кроме случаев, где
+нужна проверка ключей (`DuplicateKey`, `KeyPathConflict`) или исходных
+байтов UTF-8 до разбора (`InvalidUtf8`). Tree-sitter
+строит синтаксическое дерево для редакторов и не заменяет
+семантическую проверку эталонного Rust-парсера.
 
 ## Лицензия
 
-MIT OR Apache-2.0. См. [LICENSE-MIT](LICENSE-MIT) и [LICENSE-APACHE](LICENSE-APACHE).
+Двойная лицензия — **MIT OR Apache-2.0**; см.
+[LICENSE-MIT](LICENSE-MIT) и [LICENSE-APACHE](LICENSE-APACHE).
 
 ## Другие репозитории Ktav
 

package/README.zh.md

@@ -3,7 +3,7 @@
 > 面向 [Ktav (כְּתָב)](https://github.com/ktav-lang/spec)（书面配置
 > 格式）的 [tree-sitter](https://tree-sitter.github.io/) 语法。
 
-**语言：** [English](README.md) · [Русский](README.ru.md) · **简体中文**
+**Languages:** [English](README.md) · [Русский](README.ru.md) · **简体中文**
 
 **演练场：** 在浏览器中互转 JSON / YAML / TOML / INI ⇄ Ktav — **[ktav-lang.github.io](https://ktav-lang.github.io/)**。
 
@@ -18,8 +18,9 @@
 ## 什么是 Ktav？
 
 Ktav（希伯来语 **כְּתָב**，"书写"）是一种纯文本配置格式。形态与
-JSON 相同（标量、数组、对象、`null`、布尔值），但字符串无引号、无逗
-号，并使用点式键（`server.port: 8080`）表示嵌套。完整规范——所有官
+JSON 相同（标量、数组、对象、`null`、布尔值），但字符串不加引号；
+普通条目之间不使用逗号（内联复合结构中会使用逗号），并使用点式键
+（`server.port: 8080`）表示嵌套。完整规范——所有官
 方 Ktav 实现共同遵循的——在
 [`ktav-lang/spec`](https://github.com/ktav-lang/spec) 仓库中。
 
@@ -32,12 +33,12 @@ JSON 相同（标量、数组、对象、`null`、布尔值），但字符串无
 
 ## 安装
 
-### Rust
+### Rust（`tree-sitter` crate）
 
 ```toml
 [dependencies]
-tree-sitter      = "0.25"
-tree-sitter-ktav = "0.6.0"
+tree-sitter         = "0.25"
+tree-sitter-ktav    = "0.8.0"
 ```
 
 ```rust
@@ -52,7 +53,11 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
-### Node.js
+### Node.js（`tree-sitter` 包）
+
+npm 包提供原生源码，而不是预编译的 `.node` 二进制文件。
+安装需要 C/C++ 编译工具链及供 `node-gyp` 使用的 Python；
+包已包含生成的解析器，因此无需 Tree-sitter CLI。
 
 ```bash
 npm install tree-sitter tree-sitter-ktav
@@ -73,25 +78,32 @@ console.log(tree.rootNode.toString());
 
 ### Neovim（搭配 [`nvim-treesitter`](https://github.com/nvim-treesitter/nvim-treesitter)）
 
-在语法尚未上游之前，请在配置中手动注册：
+当前 `nvim-treesitter` 主分支已不再使用旧的
+`get_parser_configs()` 注册 API。请从语法仓库构建解析器库，再通过
+Neovim 的 Tree-sitter API 加载。构建此语法时，CLI 会自动包含
+`src/scanner.c`：
 
 ```lua
-require("nvim-treesitter.parsers").get_parser_configs().ktav = {
-  install_info = {
-    url = "https://github.com/ktav-lang/tree-sitter-ktav",
-    files = { "src/parser.c" },
-    branch = "main",
-  },
-  filetype = "ktav",
-}
-
+require("nvim-treesitter").setup({})
 vim.filetype.add({ extension = { ktav = "ktav" } })
+vim.treesitter.language.add("ktav", {
+  path = vim.fn.stdpath("data") .. "/site/parser/ktav.so",
+})
+vim.api.nvim_create_autocmd("FileType", {
+  pattern = "ktav",
+  callback = function() vim.treesitter.start() end,
+})
 ```
 
-随后执行 `:TSInstall ktav`。把 `queries/highlights.scm`、
-`queries/locals.scm` 与 `queries/injections.scm` 放入
-`~/.config/nvim/queries/ktav/`（或让 `nvim-treesitter` 自动从仓库
-拉取）。
+先创建目标 `parser` 目录。例如，在 Unix 上运行
+`mkdir -p ~/.local/share/nvim/site/parser`，然后在语法仓库中执行
+`npx tree-sitter build --output
+~/.local/share/nvim/site/parser/ktav.so`。此目录和 `.so` 扩展名是 Unix
+示例；请按平台使用 `stdpath("data")` 对应的路径及共享库扩展名（例如
+Windows 上的 `.dll`），并同时更新构建命令和 Lua 配置。若显式列出源文件，
+请同时包含 `src/parser.c` 和 `src/scanner.c`。将 `queries/highlights.scm`、
+`queries/locals.scm` 和 `queries/injections.scm` 复制到
+`~/.config/nvim/queries/ktav/`。
 
 ### Helix
 
@@ -103,7 +115,7 @@ name      = "ktav"
 scope     = "source.ktav"
 file-types = ["ktav"]
 roots     = []
-comment-token = "#"
+comment-token = "##"
 indent    = { tab-width = 4, unit = "    " }
 
 [[grammar]]
@@ -121,38 +133,47 @@ tree-sitter 的编辑器都可以在解析器构建后直接使用。
 
 ## 节点类型
 
-语法生成以下命名节点：
+以下是 CST（参见 `src/node-types.json`）中的代表性命名节点：
 
 | 节点                      | 捕获内容                                      |
 |---------------------------|-----------------------------------------------|
 | `source_file`             | 整个文档                                      |
-| `comment`                 | `#` 行注释                                    |
+| `comment`                 | `##` 行注释                                   |
 | `blank_line`              | 空行                                          |
 | `object_pair`             | `key SEP value` 行                            |
-| `key` / `dotted_key`      | 键部分（可包含 `.` 分隔符）                   |
-| `sep_string` / `sep_raw` / `sep_int` / `sep_float` | 四种分隔符           |
-| `keyword` / `kw_null` / `kw_true` / `kw_false`     | 关键字               |
-| `scalar`                  | 通用单行值正文                                |
+| `key` / `dotted_key`      | 键及其点分段                                   |
+| `quoted_key_segment`      | `"…"`、`'…'` 或 `` `…` `` 形式的键段（§ 5.3.3） |
+| `escape_sequence`         | 键或内联值中的转义（§ 3.7）                    |
+| `sep_string` / `sep_raw`  | 键值对分隔符 `:` 和 `::`                      |
+| `keyword` / `kw_null` / `kw_true` / `kw_false`     | 关键字（整行值与内联值） |
+| `integer` / `float`       | 数值（整行值与内联值，按 § 5.2 推断）          |
+| `scalar` / `raw_scalar`   | 普通及 raw 单行值                              |
+| `top_scalar`              | 顶层数组中的字符串条目                         |
+| `inline_scalar` / `inline_raw_scalar` | 内联结构中 `:` / `::` 之后的字符串值 |
 | `compound_object`         | `{` … `}` 块                                  |
 | `compound_array`          | `[` … `]` 块                                  |
-| `array_item`              | 数组中的单个元素                              |
+| `inline_object` / `inline_array` | 内联结构及其逗号分隔的条目               |
+| `inline_pair` / `inline_value` | 内联结构中的键值对和值                   |
+| `array_item` / `top_array_item` | 复合数组和顶层数组中的条目               |
 | `multiline_stripped`      | `(` … `)` 块                                  |
 | `multiline_verbatim`      | `((` … `))` 块                                |
 | `multiline_content_line`  | 多行字符串内的单行                            |
 | `empty_object` / `empty_array` / `empty_paren` / `empty_double_paren` | 内联空形式 |
-| `empty_value`             | 分隔符紧跟行尾                                |
+| `empty_value`             | 分隔符后接最长的允许空白序列，直到行尾或真正的文件末尾 |
 
-`object_pair` 暴露字段 `key`、`separator`、`value`；`array_item`
-暴露 `marker`（可选）和 `value`。
+`object_pair` 和 `inline_pair` 暴露字段 `key`、`separator`、`value`
+（`inline_pair.value` 可选）；`array_item` 与 `top_array_item` 暴露必需的
+`value` 和可选的 `marker`。
 
 ## 从源码构建
 
 ```bash
-git clone https://github.com/ktav-lang/tree-sitter-ktav.git
+git clone --recurse-submodules https://github.com/ktav-lang/tree-sitter-ktav.git
 cd tree-sitter-ktav
-npm install
-npx tree-sitter generate     # 生成 src/parser.c
-npx tree-sitter test         # 运行语料库
+npm ci                       # 安装 lock 文件固定的 tree-sitter-cli 0.26.8
+npx tree-sitter generate     # 重新生成 src/parser.c 等文件
+npx tree-sitter test         # 运行 tree-sitter 语料库
+cargo test                   # 运行 Rust 测试，包括规范一致性测试
 ```
 
 `src/parser.c`、`src/grammar.json`、`src/node-types.json` 与
@@ -161,15 +182,17 @@ CLI 即可构建。
 
 ## 状态
 
-`0.6.0` — 实现 [Ktav 0.6.0](https://github.com/ktav-lang/spec/blob/main/versions/0.6/spec.md)。
-语法接受所有合法的 Ktav 0.6.0 文档（对 spec 仓库下
-`tests/valid/*.ktav` 全部用例验证通过）。它是一个语法接受器，而非
-严格的规范校验器——少数语法接受但规范拒绝的边界情况（主要是 § 6.10
-"标记后必须有空格"）见 [`CHANGELOG.md`](CHANGELOG.md)。
+`0.8.0` — 面向 [Ktav 0.8.0](https://github.com/ktav-lang/spec/blob/main/versions/0.8/spec.md) 语法的 Tree-sitter 语法包。
+语法可无错误地解析所有固定的 spec 0.8 有效样例，并将每个根
+Object/Array 与 JSON 预期结果核对。除需验证键的错误（`DuplicateKey`、
+`KeyPathConflict`）或解析前检查原始 UTF-8 字节的错误（`InvalidUtf8`）外，
+每个无效样例都会产生语法错误。
+Tree-sitter 为编辑器构建语法树，不代替参考 Rust 解析器的语义校验。
 
 ## 许可证
 
-MIT OR Apache-2.0。详见 [LICENSE-MIT](LICENSE-MIT) 和 [LICENSE-APACHE](LICENSE-APACHE)。
+基于 **MIT OR Apache-2.0** 双重许可 —— 详见
+[LICENSE-MIT](LICENSE-MIT) 与 [LICENSE-APACHE](LICENSE-APACHE)。
 
 ## 其他 Ktav 仓库