yini-parser 1.5.0 → 1.6.1

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # CHANGELOG
 
+## 1.6.1 - 2026 June  
+- **Fixed:** Aligned parser behavior with the external `yini-test` conformance suite for shebang-like comment lines, misplaced `@yini` directives, and triple-quoted string line endings.
+- **Fixed:** `#!` lines after an opening `@yini` marker are now treated as comment trivia, while `@yini` directives after document content are reported as syntax errors in both lenient and strict mode.
+- **Fixed:** Triple-quoted raw and Classic strings now normalize physical `CRLF`/`CR` line endings to `LF`, producing stable output across platforms.
+- **Fixed:** Diagnostic line numbers no longer shift by one after a valid shebang line; strict-mode trailing-comma errors now point to the actual physical source line.
+- **Fixed:** Removed the outdated warning `Warning: Strict initialMode is not yet fully implemented.` Strict mode is now implemented against the latest YINI Specification RC 6.
+- **Improved:** Parse errors now use a concise `YiniParseError`, and missing `/END` messages clearly explain that `/END` is required in strict mode but optional in the default lenient mode.
+
+## 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`.

package/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2024 Gothenburg, Marko K. S. (Sweden via Finland).
+   Copyright 2026 Marko K. Seppänen
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -1,12 +1,52 @@
 # yini-parser
-> **Readable configuration for Node.js and TypeScript/JavaScript — without YAML footguns or JSON noise.**  
 
-The official TypeScript / Node.js parser for **YINI** (by the YINI-lang project) — a human-friendly configuration format with clear structure, nested sections, 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.  
+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.  
 
 [![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)  
 
+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
 
 ```sh
@@ -18,27 +58,43 @@ 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).
+### Modes and `/END`
+
+`yini-parser` runs in lenient mode by default. In lenient mode, the document terminator `/END` is optional.
+
+Strict mode requires `/END` unless you explicitly override `requireDocTerminator`:
+
+```ts
+const config = YINI.parseFile('./config.yini', {
+  strictMode: true,
+})
+```
+
+If strict mode reports a missing `/END`, either add `/END` as the final significant line or parse with the default lenient mode.
+
+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 for real-world 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.
   
 ---
 
@@ -47,16 +103,17 @@ console.log(config.App.Features.caching)  // true
 ![YINI Config Example](./samples/basic.yini.png)
 Source: [basic.yini](./samples/basic.yini)
 
-- ▶️ [Demo Apps](https://github.com/YINI-lang/yini-demo-apps/tree/main) with complete usage examples.
+- [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 easy 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 +137,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 +187,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,36 +196,141 @@ 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.
 
-This parser is validated through regression and smoke tests to help ensure stable, predictable parsing across default, strict, and metadata-enabled modes.
+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:
+
+### 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`.
 
-- ➡️ [Read the YINI Specification](https://yini-lang.org/refs/specification)  
-  *Full syntax and format reference.*
+The package depends on the ANTLR JavaScript/TypeScript runtime used by the generated lexer and parser while parsing.
 
-- ➡️ [YINI CLI on GitHub](https://github.com/YINI-lang/yini-cli)  
-  *CLI tooling for working with YINI files.*
+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.
+
+---
 
-- ➡️ [Demo Apps](https://github.com/YINI-lang/yini-demo-apps/tree/main)  
-  *Complete basic usage examples.*
+## Feedback and bug reports
 
-- ➡️ [YINI-lang Project](https://github.com/YINI-lang)  
-  *Repositories and related ecosystem projects.*
+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.
+
+It has also been run against `yini-test-suite` v0.3.0, the external [YINI conformance test suite](https://github.com/YINI-lang/yini-test-suite), with all TypeScript parser cases passing.
+
+---
+
+## 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
-Feedback, bug reports, feature requests, and code contributions are welcome.
+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.
@@ -179,13 +341,13 @@ If this library is useful to you, a GitHub star helps more people discover the p
 ## License
 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, 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,4 +1,4 @@
-import { ParsedObject, ParseOptions, PreferredFailLevel, YiniParseResult } from './types';
+import { ParsedObject, ParseForToolingOptions, ParseOptions, PreferredFailLevel, YiniParseResult, YiniToolingParseResult } from './types';
 /**
  * This class is the main public API. It exposes `parse(..)` and `parseFile(..)`
  * as the primary entry points, while the implementation details remain internal.
@@ -69,11 +69,13 @@ 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 console output, including errors and warnings.
+     * @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,
@@ -101,6 +103,17 @@ 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.
      *
@@ -155,11 +168,13 @@ 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 console output, including errors and warnings.
+     * @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,

package/dist/YINI.js

@@ -53,6 +53,110 @@ 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('directive') && text.includes('wrong place')) {
+            return 'misplaced-directive';
+        }
+        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.