@o3co/ts.hocon 1.11.0 → 1.13.0

package/README.ja.md

@@ -80,6 +80,7 @@ HOCON は単なるシリアライズ形式ではなく、**プログラムに注
 - `+=` 追加演算子
 - `include "file.conf"` および `include file("file.conf")` ディレクティブ
 - トリプルクォート文字列（`"""..."""`）
+- HOCON エミッタ（`renderHocon()`）— 解決済み `Config` を HOCON テキストとして出力。再パースすると同一の値ツリーになる（E18 ラウンドトリップ契約）
 - 同期・非同期 API（`parse` / `parseAsync` / `parseFile` / `parseFileAsync`）
 - ESM + CJS デュアルパッケージ（全エントリポイントを CI で両形式ロード検証）
 - [Zod](https://zod.dev/) スキーマバリデーション統合（オプション）
@@ -121,6 +122,7 @@ parseFileAsync(path: string, opts?: ParseOptions): Promise<Config>
 | `keys()` | `string[]` | — |
 | `withFallback(fallback)` | `Config` | — |
 | `toObject()` | `unknown` | — |
+| `renderHocon()` | `string` | 未解決の場合 |
 
 ### Zod 統合
 
@@ -193,18 +195,17 @@ description = """
 
 ## 仕様準拠
 
-[Lightbend HOCON 仕様](https://github.com/lightbend/config/blob/main/HOCON.md) への準拠状況は [`docs/spec-compliance.md`](docs/spec-compliance.md) に項目単位で記載しています。以下の表は 2026-05-13 時点のスナップショットです — 最新値は [`xx.hocon/docs/compliance-matrix.md`](https://github.com/o3co/xx.hocon/blob/main/docs/compliance-matrix.md) を参照してください。
+[Lightbend HOCON 仕様](https://github.com/lightbend/config/blob/main/HOCON.md) への準拠状況は [`docs/spec-compliance.md`](docs/spec-compliance.md) に項目単位で記載しており、以下の表はそこから計算されます — `tests/docs.test.ts` が再計算し、表がずれるとビルドが fail します。実装横断のロールアップは [`xx.hocon/docs/compliance-matrix.md`](https://github.com/o3co/xx.hocon/blob/main/docs/compliance-matrix.md) を参照してください。
 
 | 指標                                   | 状況          |
 | -------------------------------------- | ------------- |
-| 仕様全体（out-of-scope を含む）        | **74.2%**     |
-| In-scope のみ                          | **83.3%**     |
+| 仕様全体（out-of-scope を含む）        | **90.0%**     |
+| In-scope のみ                          | **100.0%**    |
 | Lightbend `test01`–`test13` テスト群   | 13/13 合格    |
 
-v0.1.0 で未対応の機能:
+未対応の機能:
 - `include url(...)`
 - `include classpath(...)`
-- `.properties` ファイルのパース
 
 ## パフォーマンス
 
@@ -350,6 +351,7 @@ const merged = cfg.withFallback(base).resolve()
 | `@o3co/ts.hocon/adapters/properties` | — | `java.util.Properties`。`include` と構文レイヤーを共有 |
 | `@o3co/ts.hocon/adapters/env` | — | プレフィックス付き名前空間の一括マウント。`.env` の読み込みも可能 |
 | `@o3co/ts.hocon/adapters/jsonc` | — | コメントと末尾カンマを許す JSON |
+| `@o3co/ts.hocon/adapters/json5` | — | JSON5 1.0.0。手書き scanner で依存ゼロ |
 | `@o3co/ts.hocon/adapters/toml` | `smol-toml` | オプショナルなピア依存 |
 | `@o3co/ts.hocon/adapters/yaml` | `yaml` 2.9.x | オプショナルなピア依存。スカラー解決はそのライブラリの答えで、`version: '1.2'` を明示してドリフトを防止 |
 

package/README.md

@@ -86,6 +86,7 @@ On top of that, HOCON combines the readability of YAML with the structure of JSO
 - `include "file.conf"` and `include file("file.conf")` directives
 - Triple-quoted strings (`"""..."""`)
 - Duration and byte size parsing (`getDuration()`, `getBytes()`)
+- HOCON emitter (`renderHocon()`) — renders a resolved `Config` back to HOCON text; re-parsing yields the same value tree (E18 round-trip contract)
 - Sync and async API (`parse` / `parseAsync` / `parseFile` / `parseFileAsync`)
 - ESM + CJS dual package (every entrypoint smoke-tested in both formats on each CI run)
 - Optional [Zod](https://zod.dev/) integration for schema validation
@@ -134,6 +135,7 @@ parseFileAsync(path: string, opts?: ParseOptions): Promise<Config>
 | `resolveWith(source, opts?)` | `Config` | source unresolved, or unresolvable substitution |
 | `isResolved()` | `boolean` | — |
 | `toObject()` | `unknown` | — |
+| `renderHocon()` | `string` | unresolved |
 
 ### Deferred resolution API (E12)
 
@@ -265,12 +267,12 @@ Supported byte units: `B`, `KB`/`KiB`, `MB`/`MiB`, `GB`/`GiB`, `TB`/`TiB` (and l
 
 ## Spec Compliance
 
-Conformance against the [Lightbend HOCON specification](https://github.com/lightbend/config/blob/main/HOCON.md) is tracked at item granularity in [`docs/spec-compliance.md`](docs/spec-compliance.md). The table below is a snapshot as of 2026-05-13; see [`xx.hocon/docs/compliance-matrix.md`](https://github.com/o3co/xx.hocon/blob/main/docs/compliance-matrix.md) for live cross-impl values.
+Conformance against the [Lightbend HOCON specification](https://github.com/lightbend/config/blob/main/HOCON.md) is tracked at item granularity in [`docs/spec-compliance.md`](docs/spec-compliance.md), which is the source these rates are computed from — `tests/docs.test.ts` recomputes them and fails the build if this table drifts. See [`xx.hocon/docs/compliance-matrix.md`](https://github.com/o3co/xx.hocon/blob/main/docs/compliance-matrix.md) for the cross-implementation roll-up.
 
 | Metric                                | Status        |
 | ------------------------------------- | ------------- |
-| Spec total (incl. out-of-scope)       | **74.2%**     |
-| In-scope only                         | **83.3%**     |
+| Spec total (incl. out-of-scope)       | **90.0%**     |
+| In-scope only                         | **100.0%**    |
 | Lightbend `test01`–`test13` suite     | 13/13 passing |
 
 **Extra-spec conventions (E-series) — implementation status:**
@@ -289,10 +291,6 @@ Supported since v0.2.0 (P1):
 
 - `.properties` file parsing
 
-### Stricter than Lightbend
-
-- **S8.6 leading-hyphen rejection** (Unreleased): `a = -foo`, `a = -bar`, `a = -` etc. now raise a lex error per HOCON.md L270–276, where Lightbend silently falls back to unquoted strings. Mitigation: quote the value (`a = "-foo"`). See [CHANGELOG](CHANGELOG.md#unreleased) and [`docs/spec-compliance.md`](docs/spec-compliance.md) §S8.6.
-
 ## Performance
 
 ### ts.hocon Parsing Cost
@@ -325,7 +323,7 @@ For typical application configs (loaded once at startup), the parsing cost is ne
 
 ### Feature Comparison with node-config
 
-ts.hocon provides significantly richer configuration capabilities compared to [node-config](https://github.com/node-config/node-config) (JSON):
+Feature-level comparison with [node-config](https://github.com/node-config/node-config) **v4.4.2** reading JSON config files, as of 2026-07-26:
 
 | Feature | ts.hocon | node-config (JSON) |
 |---|---|---|
@@ -439,6 +437,7 @@ Deferring resolution matters: the plain `parse` resolves as it goes, so a
 | `@o3co/ts.hocon/adapters/properties` | — | `java.util.Properties`, sharing the `include` syntax layer |
 | `@o3co/ts.hocon/adapters/env` | — | Bulk-mounts a prefixed namespace; also reads `.env` |
 | `@o3co/ts.hocon/adapters/jsonc` | — | JSON with comments and trailing commas |
+| `@o3co/ts.hocon/adapters/json5` | — | JSON5 1.0.0, hand-rolled scanner, zero dependencies |
 | `@o3co/ts.hocon/adapters/toml` | `smol-toml` | Optional peer dependency |
 | `@o3co/ts.hocon/adapters/yaml` | `yaml` 2.9.x | Optional peer dependency; scalar resolution is that library's answer, with `version: '1.2'` declared so it cannot drift |
 
@@ -462,11 +461,12 @@ cfg.getString('"foo.bar"')   // "dotted"  — one key whose name contains a dot
 cfg.getString('foo.bar')     // "nested"  — foo -> bar
 ```
 
-### Numbers from JSONC and YAML
+### Numbers from JSONC, JSON5 and YAML
 
 Integers are ingested losslessly: an integer literal too wide for a JS `number`
 keeps its digits instead of being rounded, and one outside the int64 range is
-refused rather than silently mangled. What you get back depends on the getter:
+refused rather than silently mangled (JSON5's hex integers included). What you
+get back depends on the getter:
 
 ```ts
 const cfg = parseJsonc('{"id": 9007199254740993}')
@@ -498,6 +498,15 @@ When parsing untrusted HOCON input, be aware of:
 - **Path traversal in includes:** a relative `include` path resolves against `baseDir` and can climb out of it with `..` segments to reach sensitive files such as `/etc/passwd`. Use a custom `readFileSync`/`readFile` that validates paths if parsing untrusted input.
 - **Input size:** The parser has no built-in input size limit. For untrusted input, validate size before calling `parse()`.
 - **Include depth:** Limited to 50 levels to prevent stack overflow from deep include chains.
+- **Mapped path depth:** an environment variable's `__` segments and a
+  `.properties` dotted key are limited to 64 segments. One name produces one
+  arbitrarily deep chain, so without the cap a single long variable name was
+  enough to exhaust the stack. rs.hocon and py.hocon cap the same mapping at 64.
+- **Document nesting depth:** not capped. A document nested past what the
+  engine's stack holds fails as `ParseError` or `ConfigError` — never as a bare
+  `RangeError` — but the depth at which that happens depends on how deep the
+  calling code already is, so validate size before parsing untrusted input (see
+  above) rather than relying on a fixed level.
 - **Prototype pollution:** keys named `__proto__`, `constructor` or `prototype`
   are **kept as ordinary keys** — a `.properties` file or environment variable
   may legitimately use them, and dropping them would be silent data loss.