yini-parser 1.4.3 → 1.6.0

package/CHANGELOG.md

@@ -1,6 +1,58 @@
 # CHANGELOG
 
+## 1.6.0 - 2026 May
+- **Improved:** Reduced the published npm package contents by excluding development-only build output, internal tool output, and duplicate `dist/src` declaration files from the package tarball.
+- **Added:** Implemented a `yini-test` adapter (`tools/yini-test-adapter.ts`) for testing this parser against an external conformance corpus. The `yini-test` corpus/test runner is planned to be made public and released separately in the future.
+- **Updated:** Parser behavior aligned with YINI Specification `v1.0.0-RC.6`, including:
+  * **Changed:** `#` now always starts a comment outside string literals. No whitespace is required before or after `#`.
+  * **Added:** Support for explicit hexadecimal notation using `hex:` as an alternative to `0x...`.
+  * **Removed:** Support for `#` as a hexadecimal number prefix. Hexadecimal numbers must now use `0x...` or `hex:...`.
+  * **Removed:** Internal handling of Hyper Strings (H-Strings), simplifying string parsing and reducing parser complexity.
+  * **Added:** Lenient mode now accepts `=` as an alternative inline object member separator. The canonical form remains `key: value`.
+  * **Changed:** Strict mode rejects `=` inside inline objects; inline object members must use `:`.
+  * **Changed:** String concatenation now uses the updated grammar model:
+  - `+` performs explicit string concatenation only; it does not define numeric addition.
+  - In strict mode, all operands must be string literals.
+  - In lenient mode, the first operand must be a string literal; later operands may be string, number, boolean, or null literals.
+  - If the expression does not begin with a string literal, it is rejected rather than treated as arithmetic.
+  - A line break is allowed after `+`, but not before it.
+  - Lists and inline objects are invalid concatenation operands.
+  * **Added:** Empty-document handling by mode:
+    - In lenient mode, empty documents now parse successfully with a warning.
+    - In strict mode, empty documents now produce an error.
+  * **Improved:** Orphan root-level members in lenient mode are mounted directly on the resulting top-level object.
+  * **Improved:** Parser/runtime handling of empty inline input and final newline normalization.
+  * **Updated:** Tests for string concatenation, empty documents, inline object separators, hash comments, and hex notation.
+  * **Added:** Support for YINI mode declarations: `@yini strict` and `@yini lenient`. Mode declarations validate the active parser mode; they do not switch parser mode. `@yini strict` parsed in lenient mode produces a mode-mismatch error, while `@yini lenient` parsed in strict mode remains valid but produces a mode-mismatch warning.
+  * **Updated:** Shebang handling. A shebang is recognized only when `#!` is the first two non-BOM characters of the document. Valid shebang lines are ignored. Misplaced shebang-like sequences are no longer treated as shebangs; they may produce warnings in lenient mode and errors in strict mode. Only the first misplaced sequence is reported.
+  * **Updated:** Section marker handling. Repeated section markers now support levels 1–9; level 10 and deeper must use numeric shorthand, for example `^10 Section`. Marker separators using `_` are supported inside repeated marker sequences, invalid separator placement and mixed marker characters are rejected, the obsolete `€` marker has been removed, and `>` is supported as an alternative marker.
+  * **Updated:** Numeric shorthand section headers. Numeric shorthand now keeps marker and depth parsing separate, requires a positive section depth, uses a single marker followed by a number, and rejects repeated markers combined with numeric shorthand, such as `^^1 Section`.
+  * **Improved:** Section header parsing and validation. Backticked section names are normalized, invalid simple names such as names with dots, hyphens, or leading digits are rejected, and parsing is aligned with the updated marker separator and alternative marker rules.
+  * **Updated:** String literal handling. Raw strings remain the default; `R`/`r` explicit raw prefixes, `C`/`c` Classic prefixes, raw triple-quoted strings, and C-triple-quoted strings are supported. C-triple-quoted strings preserve real line breaks while interpreting escape sequences. Invalid Classic string escapes are reported as errors, and invalid string members are omitted from recovered partial results in lenient `ignore-errors` mode.
+  * **Improved:** Escape sequence validation. Unicode escapes must represent valid Unicode scalar values, surrogate code points are rejected, and invalid hex, Unicode, UTF-32, and octal escapes are rejected.
+  * **Improved:** Duplicate inline object member handling. Duplicate members are no longer silently overwritten: lenient mode keeps the first member and reports duplicates; strict mode treats duplicates as errors.
+  * **Updated:** Comment and disabled-line handling. `;` is full-line only, `--` disables a line only when it is the first non-whitespace content, and `#` / `//` remain inline comment markers outside string literals.
+
+## 1.5.0 - 2026 Apr
+- **Updated:** Parser behavior aligned with YINI Specification `v1.0.0-RC.5`.
+- **Changed:** In strict mode, YINI documents must now end with the document terminator `/END`.
+- **Changed:** Strict mode now requires exactly one explicit top-level section.
+- **Updated:** Section header parsing now reflects the latest horizontal whitespace (`HSPACE`) rules from the specification.
+- **Improved:** Refined how members outside explicit sections are handled in lenient mode, and added stricter checks for top-level structure in strict mode.
+- **Improved:** Clarified and tightened how empty values and explicit `null` are handled in lenient and strict mode.
+- **Improved:** Fixed `throwOnError` option detection, clarified the related documentation, and cleaned up public parameter names.
+- **Fixed:** Made `throwOnError` work consistently together with the selected fail level.
+- **Updated:** Synced to the latest lexer and parser grammar files from the Specification Package `v1.0.0-RC.5`, with cleaned up and refined grammar files for better consistency and maintainability.
+- **Added:** Expanded validation and tests for section headers, including shorthand markers, backticked names, and invalid dotted section names.
+- **Expanded:** Improved integration and smoke test coverage for error recovery, throw behavior, null handling, fixture parsing, and section/header edge cases.
+- **Updated:** Added and validated a new large smoke/golden fixture:
+  - `tests/fixtures/smoke-fixtures/c-industrial-monitoring-and-automation-platform.smoke.yini`
+- **Improved:** Fixed and re-enabled previously skipped smoke tests:
+  - `tests/fixtures/smoke-fixtures/8-api-keys-integration.smoke.yini`
+  - `tests/fixtures/smoke-fixtures/9-app-preferences.smoke.yini`
+
 ## 1.4.3 - 2026 Apr
+- **Promoted:** YINI Parser TypeScript is now considered stable (non-beta) after iterative beta releases and refinements.
 - **Fixed:** Rebuilt the project and reduced reported vulnerabilities from 4 to 0.
   
 ## 1.4.3-beta - 2026 Mar

package/README.md

@@ -1,11 +1,51 @@
 # yini-parser
-> **Readable configuration for Node.js and TypeScript — without YAML foot-guns or JSON noise.**  
 
-The official TypeScript / Node.js parser for **YINI** (by the YINI-lang project) — a human-friendly configuration format with real structure, nested sections, comments, and predictable parsing.
+The official TypeScript / Node.js parser for **YINI** (by the YINI-lang project) — a human-readable, INI-inspired, indentation-insensitive configuration format with clear nested sections, explicit structure, comments, and predictable parsing.  
 
-YINI is designed for applications, tools, and services that need configuration that stays readable for humans without becoming vague, fragile, or hard to maintain.  
+[![npm version](https://img.shields.io/npm/v/yini-parser.svg)](https://www.npmjs.com/package/yini-parser) [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![All Test Suites](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-all-tests.yml/badge.svg)](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-all-tests.yml) [![All Regression Tests](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-regression-tests.yml/badge.svg)](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-regression-tests.yml) [![Grammar Drift Check](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-grammar-drift-check.yml/badge.svg)](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-grammar-drift-check.yml) [![npm downloads](https://img.shields.io/npm/dm/yini-parser)](https://www.npmjs.com/package/yini-parser)  
 
-[![npm version](https://img.shields.io/npm/v/yini-parser.svg)](https://www.npmjs.com/package/yini-parser) [![All Test Suites](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-all-tests.yml/badge.svg)](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-all-tests.yml) [![All Regression Tests](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-regression-tests.yml/badge.svg)](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-regression-tests.yml) [![Grammar Drift Check](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-grammar-drift-check.yml/badge.svg)](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-grammar-drift-check.yml) [![npm downloads](https://img.shields.io/npm/dm/yini-parser)](https://www.npmjs.com/package/yini-parser)
+YINI is intended to emphasize clarity, readability, explicit structure, and predictable parsing, while remaining simple, but not simplistic, and without relying on implicit or indentation-sensitive structure.
+
+## Copy-paste test
+
+Test the package in under one minute.
+
+Install:
+
+```sh
+npm install yini-parser
+```
+
+Parse a YINI string:
+
+```ts
+import YINI from 'yini-parser'
+
+const data = YINI.parse(`
+^ Application
+name = "demo"
+
+^^ Server
+port = 8080
+`)
+
+console.log(data)
+```
+
+Expected output:
+
+```ts
+{
+  Application: {
+    name: 'demo',
+    Server: {
+      port: 8080,
+    },
+  },
+}
+```
+
+---
 
 ## Quick Start
 
@@ -18,45 +58,48 @@ import YINI from 'yini-parser'
 
 const config = YINI.parse(`
 ^ App
-name = 'My App'
-darkMode = true
+name     = 'My App'
+list     = ['web', 'api']
+darkMode = true  // Yes/On works too
 
     ^^ Features
     caching = on
+    object  = { logging: true, mode: 'debug' }
 `)
 
 console.log(config.App.name)              // My App
 console.log(config.App.Features.caching)  // true
 ```
 
-➡️ Learn more in the [YINI specification and documentation](https://yini-lang.org/refs/specification).
+See the [YINI specification and documentation](https://yini-lang.org/refs/specification?utm_source=github&utm_medium=referral&utm_campaign=yini_parser_ts&utm_content=readme).
 
 ---
 
-## 🙋‍♀️ Why try YINI?
+## Format characteristics
 
-- **Readable by humans** — Less noisy than JSON, less fragile than indentation-driven formats.
-- **Structured enough for real configuration** — Sections, nested sections, lists, objects, booleans, and null.
-- **Predictable parsing** — Explicit syntax with clear rules.
-- **Easy to use from TypeScript/Node.js** — Parse from strings or files in a few lines.
+- **Human-readable** — Uses explicit syntax and indentation-independent structure.
+- **Structured configuration model** — Supports sections, nested sections, lists, objects, booleans, and null.
+- **Predictable parsing** — Explicit syntax with clear rules and deterministic parsing behavior.
+- **TypeScript and Node.js integration** — Supports parsing from strings and files.
   
 ---
 
 ## What YINI looks like in practice
-> A basic YINI configuration example, showing a section, nested section, comments:  
+> A basic YINI configuration example, showing a section, a nested section, and comments:  
 ![YINI Config Example](./samples/basic.yini.png)
 Source: [basic.yini](./samples/basic.yini)
 
-- ▶️ Link to [Demo Apps](https://github.com/YINI-lang/yini-demo-apps/tree/main) with complete basic usage.
+- [Demo Apps](https://github.com/YINI-lang/yini-demo-apps/tree/main) with usage examples.
 
 ---
 
-## Why YINI works well for configuration
+## Configuration-oriented design
 - **Indentation-independent structure:** Spaces and tabs never change meaning, so files can be reformatted without changing structure.
-- **Explicit nesting:** Hierarchy is defined with section markers like `^`, `^^`, and `^^^`, making large configurations easier to scan and refactor.
+- **Explicit nesting:** Hierarchy is defined with section markers such as `^`, `^^`, and `^^^`, rather than by indentation.
 - **Multiple data types:** Supports booleans (`true` / `false`, `yes` / `no`, etc.), numbers, lists, and inline objects, with explicit string syntax.
-- **Comment support:** YINI supports multiple comment styles (`#`, `//`, `/* ... */`, and `;`), making it easier to document configuration directly in the file.
-- **Predictable parsing:** Clear rules with optional strict and lenient modes for different use cases.
+- **Comment support:** YINI supports `//`, `#`, block comments (`/* ... */`), and full-line `;` comments for documenting configuration directly in the file.
+- **Clear hash comments:** Outside string literals, `#` always starts a comment; hexadecimal values use `0x...` or `hex:...`.
+- **Predictable parsing:** Clear rules with optional strict and lenient modes (enforced by the parser) for different use cases.
 
 ---
 
@@ -80,7 +123,7 @@ pnpm add yini-parser
 ```
 
 ### Node.js (CommonJS)
-**Note:** Only a default export (YINI) is provided. Named imports are not supported.
+**Note:** The default export is the main API. Named exports such as `parse`, `parseFile`, and `parseForTooling` are also available from the package entry.
 ```js
 const YINI = require('yini-parser').default;
 // If your setup handles default interop differently, try:
@@ -130,7 +173,7 @@ const configFromFile = YINI.parseFile('./config.yini');
 
 ## 📂 More Examples
 
-- ▶️ Explore more [YINI examples](https://yini-lang.org/learn-yini/examples/?utm_source=yini-parser-ts&utm_medium=github&utm_campaign=repo-link&utm_content=readme).
+- Additional [YINI examples](https://yini-lang.org/learn-yini/examples/?utm_source=yini-parser-ts&utm_medium=github&utm_campaign=repo-link&utm_content=readme).
 
 ### Example 2
 > A real-world YINI configuration example, showing sections, nesting, comments, and multiple data types:  
@@ -139,30 +182,139 @@ Source: [config.yini](./samples/config.yini)
 
 ---
 
-## 🧪 Testing and Stability
+## Why YINI?
+
+YINI is intended for configuration files where human readability, explicit structure, and predictable parsing are more important than minimal syntax or maximum flexibility.
+
+Compared with common configuration formats:
+- **INI:** YINI supports clearer nested sections and typed values.
+- **JSON:** YINI supports comments and is easier to edit by hand.
+- **YAML:** YINI does not use indentation to define structure.
+- **TOML:** YINI uses explicit section markers for hierarchy instead of dotted table names.
+
+The same small configuration can be written in several formats:
 
-This parser is continuously validated through comprehensive regression and smoke tests, ensuring deterministic parsing behavior across default, strict, and metadata-enabled modes.
+### YINI
+```ini
+^ Application
+name = 'demo'
+environment = 'dev'
+
+^^ Server
+host = 'localhost'
+ports = [8080, 8081]
+
+^^^ TLS
+enabled = true
+mode = 'optional'
+```
+
+- `Application` contains the top-level application settings.
+- `Server` is nested under `Application`.
+- `TLS` is nested under `Server`.
+- The section markers `^` make the nesting explicit. Indentation is optional and not required for structure.
+- Strings can use either `'` or `"`.
+
+### JSON
+```json
+{
+  "Application": {
+    "name": "demo",
+    "environment": "dev",
+    "Server": {
+      "host": "localhost",
+      "ports": [8080, 8081],
+      "TLS": {
+        "enabled": true,
+        "mode": "optional"
+      }
+    }
+  }
+}
+```
+
+### YAML
+```yaml
+Application:
+  name: demo
+  environment: dev
+  Server:
+    host: localhost
+    ports:
+      - 8080
+      - 8081
+    TLS:
+      enabled: true
+      mode: optional
+```
+
+### TOML
+```toml
+[Application]
+name = "demo"
+environment = "dev"
+
+[Application.Server]
+host = "localhost"
+ports = [8080, 8081]
+
+[Application.Server.TLS]
+enabled = true
+mode = "optional"
+```
+
+Note: YINI may not be the right choice when you need mature ecosystem support, existing schema tooling, or maximum compatibility with infrastructure that already expects JSON, YAML, or TOML.
 
 ---
 
-## Links
-- ➡️ [YINI Homepage](https://yini-lang.org)  
-  *Tutorials, guides, and examples.*
+## Parser implementation
+
+`yini-parser` uses TypeScript/JavaScript parser code generated by ANTLR.
+
+The generated parser files are included in the published npm package. Users do **not** need Java or the ANTLR generator tool to install or use `yini-parser`.
 
-- ➡️ [YINI CLI on GitHub](https://github.com/YINI-lang/yini-cli)  
-  *CLI tooling for working with YINI files.*
+The package depends on the ANTLR JavaScript/TypeScript runtime used by the generated lexer and parser while parsing.
 
-- ➡️ [YINI Project](https://github.com/YINI-lang)  
-  *Repositories and related ecosystem projects.*
+The ANTLR generator JAR is only needed by maintainers when regenerating parser sources from the grammar, and it is not included in the published npm package.
+
+---
+
+## Feedback and bug reports
+
+If you find a problem, please open an issue on GitHub:
+
+- [Report a bug or issue](https://github.com/YINI-lang/yini-parser-typescript/issues)
+
+When reporting parser behavior, it is helpful to include:
+- The YINI input that caused the issue.
+- The expected result.
+- The actual result or error message.
+- The installed `yini-parser` version.
+- The Node.js version used.
+
+---
+
+## 🧪 Testing and Stability
+
+This parser is covered by smoke, integration, and regression tests across lenient, strict, and metadata-enabled modes.
+
+---
+
+## Links
+- [YINI Homepage](https://yini-lang.org)  
+- [YINI Specification](https://yini-lang.org/refs/specification)  
+- [YINI CLI on GitHub](https://github.com/YINI-lang/yini-cli)  
+- [YINI Demo Apps](https://github.com/YINI-lang/yini-demo-apps/tree/main)  
+- [YINI-lang Project](https://github.com/YINI-lang)  
 
 ---
 
 ## 🤝 Contributing
-We welcome feedback, bug reports, feature requests, and code contributions!
+Bug reports, feature requests, discussions, and code contributions are welcome.
 - [Open an Issue](https://github.com/YINI-lang/yini-parser-typescript/issues)
 - [Start a Discussion](https://github.com/YINI-lang/yini-parser-typescript/discussions)
   
-If this library is useful to you, a GitHub star helps more people discover the project and supports future development.
+GitHub Issues and Discussions are available for feedback and project discussion.
 
 ### Documentation
 - [Project Setup](https://github.com/YINI-lang/yini-parser-typescript/blob/main/docs/Project-Setup.md) — How to run, test, and build the project, etc.
@@ -171,15 +323,15 @@ If this library is useful to you, a GitHub star helps more people discover the p
 ---
 
 ## License
-This project is licensed under the Apache-2.0 license — see the [LICENSE](./LICENSE) file for details.
+This project is licensed under the Apache License 2.0 — see the [LICENSE](./LICENSE) file for details.
 
-In this project on GitHub, the `libs` directory contains third party software and each is licensed under its own license which is described in its own license file under the respective directory under `libs`.
+In this project on GitHub, the `libs` directory contains third-party software and each is licensed under its own license which is described in its own license file under the respective directory under `libs`.
 
 ---
 
 **^YINI ≡**  
-> Readable like INI. Structured like JSON. No indentation surprises.  
+> YINI is a human-readable configuration format designed for clarity, readability, explicit structure, and predictable parsing.
 > 
-> Predictable configuration with clear rules.  
+> See the specification for syntax and format details.  
 
 [yini-lang.org](https://yini-lang.org/?utm_source=github&utm_medium=referral&utm_campaign=yini_parser_ts&utm_content=readme_footer) · [YINI-lang on GitHub](https://github.com/YINI-lang)  

package/dist/YINI.d.ts

@@ -1,8 +1,8 @@
-import { ParsedObject, ParseOptions, PreferredFailLevel, YiniParseResult } from './types';
+import { ParsedObject, ParseForToolingOptions, ParseOptions, PreferredFailLevel, YiniParseResult, YiniToolingParseResult } from './types';
 /**
- * This class is the public API, which exposes only parse(..) and
- * parseFile(..), rest of the implementation details are hidden.
- * @note Only parse and parseFile are public.
+ * This class is the main public API. It exposes `parse(..)` and `parseFile(..)`
+ * as the primary entry points, while the implementation details remain internal.
+ * @note The public parsing API is exposed through `parse(..)` and `parseFile(..)`.
  */
 export default class YINI {
     private static g_tabSize;
@@ -69,20 +69,20 @@ export default class YINI {
      *   Allowed values: `'warn-and-keep-first'` | `'warn-and-overwrite'` | `'keep-first'` (silent, first wins) | `'overwrite'` (silent, last wins) | `'error'`.
      * @param options.preserveUndefinedInMeta - Keep properties with value `undefined` inside
      *   the returned metadata. Requires: `includeMetadata = true`. Ignored otherwise.
-     * @param options.quiet - Show only errors, will suppress warnings and messages sent to the console/log.
-     *   Does not affect warnings included in returned metadata.
+     * @param options.logDiagnostics - Opt in to writing diagnostics to stderr.
+     *   Library calls do not write diagnostics by default.
+     * @param options.quiet - When `logDiagnostics = true`, show only errors.
+     *   Does not affect diagnostics included in returned metadata.
      * @param options.requireDocTerminator - Controls whether a document terminator is required.
      *   Allowed values: `'optional'` | `'warn-if-missing'` | `'required'`.
-     * @param options.silent - Suppress all output (even errors, exit code only).
+     * @param options.silent - Suppress diagnostic output, even when `logDiagnostics = true`.
      * @param options.strictMode - Sets the baseline ruleset (true = strict, false = lenient).
      *   This is only a starting point: rule-specific options (e.g., `treatEmptyValueAsNull`,
      *   `onDuplicateKey`, etc.) can override parts of that ruleset. If any overrides are given,
      *   the effective mode becomes **custom** rather than purely strict/lenient.
      * @param options.treatEmptyValueAsNull - How to treat an explicitly empty value on the
      *   right-hand side of '='. Allowed values: `'allow'` | `'allow-with-warning'` | `'disallow'`.
-     * @param options.throwOnError - Will throw on first parse error encountered.
-     * NOTE: Current default is `true`. The default will change to `false` in the next
-     * release. To avoid breaking changes, set this option explicitly.
+     * @param options.throwOnError - Throw when a parse issue reaches the active bail threshold (for example, on errors if `failLevel = 'errors'`).
      *
      * @returns {ParsedObject | YiniParseResult} The parsed YINI content.
      *
@@ -103,10 +103,21 @@ export default class YINI {
      * `
      */
     static parse(yiniContent: string, options?: ParseOptions): ParsedObject | YiniParseResult;
+    /**
+     * Parse inline YINI content for tools, editors, linters, and test runners.
+     *
+     * This API always returns a stable result object and structured diagnostics.
+     * It does not write diagnostics to stdout/stderr and does not throw for
+     * normal parse errors.
+     */
+    static parseForTooling(yiniContent: string, options?: ParseForToolingOptions): YiniToolingParseResult;
+    private static toToolingDiagnostics;
+    private static toToolingDiagnostic;
+    private static toDiagnosticCode;
     /**
      * Parse a YINI file into a JavaScript object.
      *
-     * @param yiniFile           Path to the YINI file.
+     * @param filePath           Path to the YINI file.
      * @param strictMode         If `true`, enforce strict parsing rules (e.g. require `/END`, disallow trailing commas).
      * @param failLevel          Preferred bail sensitivity level, controls if and when parsing should stop on problems:
      *   - `'auto'` (default)      : Auto‑select level (strict → `'errors'`, lenient → `'ignore-errors'`)
@@ -137,7 +148,7 @@ export default class YINI {
     /**
      * Parse a YINI file into a JavaScript object, using an options object for configuration.
      *
-     * @param yiniFile Path to the YINI file.
+     * @param filePath Path to the YINI file.
      * @param options Optional settings to customize parsing and/or results, useful if you need more control.
      *        For all options, see types/ParseOptions.
      *
@@ -157,20 +168,20 @@ export default class YINI {
      *   Allowed values: `'warn-and-keep-first'` | `'warn-and-overwrite'` | `'keep-first'` (silent, first wins) | `'overwrite'` (silent, last wins) | `'error'`.
      * @param options.preserveUndefinedInMeta - Keep properties with value `undefined` inside
      *   the returned metadata. Requires: `includeMetadata = true`. Ignored otherwise.
-     * @param options.quiet - Show only errors, will suppress warnings and messages sent to the console/log.
-     *   Does not affect warnings included in returned metadata.
+     * @param options.logDiagnostics - Opt in to writing diagnostics to stderr.
+     *   Library calls do not write diagnostics by default.
+     * @param options.quiet - When `logDiagnostics = true`, show only errors.
+     *   Does not affect diagnostics included in returned metadata.
      * @param options.requireDocTerminator - Controls whether a document terminator is required.
      *   Allowed values: `'optional'` | `'warn-if-missing'` | `'required'`.
-     * @param options.silent - Suppress all output (even errors, exit code only).
+     * @param options.silent - Suppress diagnostic output, even when `logDiagnostics = true`.
      * @param options.strictMode - Sets the baseline ruleset (true = strict, false = lenient).
      *   This is only a starting point: rule-specific options (e.g., `treatEmptyValueAsNull`,
      *   `onDuplicateKey`, etc.) can override parts of that ruleset. If any overrides are given,
      *   the effective mode becomes **custom** rather than purely strict/lenient.
      * @param options.treatEmptyValueAsNull - How to treat an explicitly empty value on the
      *   right-hand side of '='. Allowed values: `'allow'` | `'allow-with-warning'` | `'disallow'`.
-     * @param options.throwOnError - Will throw on first parse error encountered.
-     * NOTE: Current default is `true`. The default will change to `false` in the next
-     * release. To avoid breaking changes, set this option explicitly.
+     * @param options.throwOnError - Throw when a parse issue reaches the active bail threshold (for example, on errors if `failLevel = 'errors'`).
      *
      * @returns {ParsedObject | YiniParseResult} The parsed YINI content.
      *

package/dist/YINI.js

@@ -7,9 +7,9 @@ const runtime_1 = require("./core/runtime");
 const print_1 = require("./utils/print");
 const DEFAULT_TAB_SIZE = 4; // De facto "modern default" (even though traditionally/historically it's 8).
 /**
- * This class is the public API, which exposes only parse(..) and
- * parseFile(..), rest of the implementation details are hidden.
- * @note Only parse and parseFile are public.
+ * This class is the main public API. It exposes `parse(..)` and `parseFile(..)`
+ * as the primary entry points, while the implementation details remain internal.
+ * @note The public parsing API is exposed through `parse(..)` and `parseFile(..)`.
  */
 class YINI {
     /**
@@ -53,6 +53,107 @@ class YINI {
         }
         return result;
     }
+    /**
+     * Parse inline YINI content for tools, editors, linters, and test runners.
+     *
+     * This API always returns a stable result object and structured diagnostics.
+     * It does not write diagnostics to stdout/stderr and does not throw for
+     * normal parse errors.
+     */
+    static parseForTooling(yiniContent, options = {}) {
+        try {
+            const parsed = this.parse(yiniContent, {
+                ...options,
+                failLevel: 'ignore-errors',
+                includeMetadata: true,
+                includeDiagnostics: true,
+                logDiagnostics: false,
+                silent: true,
+                throwOnError: false,
+            });
+            return {
+                ok: parsed.meta.totalErrors === 0,
+                result: parsed.result,
+                diagnostics: this.toToolingDiagnostics(parsed),
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                result: {},
+                diagnostics: [
+                    {
+                        severity: 'error',
+                        code: 'parser-error',
+                        message: error instanceof Error
+                            ? error.message
+                            : String(error),
+                    },
+                ],
+            };
+        }
+    }
+    static toToolingDiagnostics(parsed) {
+        const diagnostics = parsed.meta.diagnostics;
+        if (!diagnostics) {
+            return [];
+        }
+        return [
+            ...diagnostics.errors.payload.map((issue) => this.toToolingDiagnostic(issue, 'error')),
+            ...diagnostics.warnings.payload.map((issue) => this.toToolingDiagnostic(issue, 'warning')),
+            ...diagnostics.notices.payload.map((issue) => this.toToolingDiagnostic(issue, 'notice')),
+            ...diagnostics.infos.payload.map((issue) => this.toToolingDiagnostic(issue, 'info')),
+        ];
+    }
+    static toToolingDiagnostic(issue, severity) {
+        const diagnostic = {
+            severity,
+            code: this.toDiagnosticCode(issue),
+            message: issue.message,
+        };
+        if (issue.line !== undefined) {
+            diagnostic.line = issue.line;
+        }
+        if (issue.column !== undefined) {
+            diagnostic.column = issue.column;
+        }
+        return diagnostic;
+    }
+    static toDiagnosticCode(issue) {
+        const text = [issue.message, issue.advice, issue.hint]
+            .filter((part) => Boolean(part))
+            .join(' ')
+            .toLowerCase();
+        if (text.includes('empty yini document')) {
+            return 'empty-document';
+        }
+        if (text.includes('duplicate key')) {
+            return 'duplicate-key';
+        }
+        if (text.includes('duplicate section')) {
+            return 'duplicate-section';
+        }
+        if (text.includes('yini mode declaration') &&
+            text.includes('active parser mode')) {
+            return 'YINI_MODE_MISMATCH';
+        }
+        if (text.includes('invalid escape sequence')) {
+            return 'invalid-escape-sequence';
+        }
+        if (text.includes('unterminated') && text.includes('string')) {
+            return 'unterminated-string';
+        }
+        if (text.includes('/end') && text.includes('missing')) {
+            return 'missing-document-terminator';
+        }
+        if (text.includes('shebang')) {
+            return 'misplaced-shebang';
+        }
+        if (text.includes('trailing comma')) {
+            return 'trailing-comma';
+        }
+        return issue.typeKey.replace(/_/g, '-');
+    }
     // --- Single implementation --------------------------------------------
     // Implementation method (not declared with arrow function) for both method overload signatures.
     // NOTE: Must be method declaration with NO =, arrow functions not (currently) supported for this type of method overloading.