yini-parser 1.4.3 → 1.5.0

package/CHANGELOG.md

@@ -1,6 +1,25 @@
 # CHANGELOG
 
+## 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,11 @@
 # yini-parser
-> **Readable configuration for Node.js and TypeScript — without YAML foot-guns or JSON noise.**  
+> **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 real structure, nested sections, comments, and predictable parsing.
+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.  
 
-[![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)
+[![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)  
 
 ## Quick Start
 
@@ -36,18 +36,18 @@ console.log(config.App.Features.caching)  // true
 ## 🙋‍♀️ Why try YINI?
 
 - **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.
+- **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.
   
 ---
 
 ## 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 complete usage examples.
 
 ---
 
@@ -55,7 +55,7 @@ Source: [basic.yini](./samples/basic.yini)
 - **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.
 - **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.
+- **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.
 
 ---
@@ -141,7 +141,7 @@ Source: [config.yini](./samples/config.yini)
 
 ## 🧪 Testing and Stability
 
-This parser is continuously validated through comprehensive regression and smoke tests, ensuring deterministic parsing behavior across default, strict, and metadata-enabled modes.
+This parser is validated through regression and smoke tests to help ensure stable, predictable parsing across default, strict, and metadata-enabled modes.
 
 ---
 
@@ -149,16 +149,22 @@ This parser is continuously validated through comprehensive regression and smoke
 - ➡️ [YINI Homepage](https://yini-lang.org)  
   *Tutorials, guides, and examples.*
 
+- ➡️ [Read the YINI Specification](https://yini-lang.org/refs/specification)  
+  *Full syntax and format reference.*
+
 - ➡️ [YINI CLI on GitHub](https://github.com/YINI-lang/yini-cli)  
   *CLI tooling for working with YINI files.*
 
-- ➡️ [YINI Project](https://github.com/YINI-lang)  
+- ➡️ [Demo Apps](https://github.com/YINI-lang/yini-demo-apps/tree/main)  
+  *Complete basic usage examples.*
+
+- ➡️ [YINI-lang Project](https://github.com/YINI-lang)  
   *Repositories and related ecosystem projects.*
 
 ---
 
 ## 🤝 Contributing
-We welcome feedback, bug reports, feature requests, and code contributions!
+Feedback, bug reports, feature requests, 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)
   
@@ -171,9 +177,9 @@ 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, described in its own license file under the respective directory under `libs`.
 
 ---
 

package/dist/YINI.d.ts

@@ -1,8 +1,8 @@
 import { ParsedObject, ParseOptions, PreferredFailLevel, YiniParseResult } 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;
@@ -73,16 +73,14 @@ export default class YINI {
      *   Does not affect warnings 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 all console output, including errors and warnings.
      * @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.
      *
@@ -106,7 +104,7 @@ export default class YINI {
     /**
      * 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 +135,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.
      *
@@ -161,16 +159,14 @@ export default class YINI {
      *   Does not affect warnings 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 all console output, including errors and warnings.
      * @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 {
     /**

package/dist/YINI.js.map

@@ -1 +1 @@
-{"version":3,"file":"YINI.js","sourceRoot":"","sources":["../src/YINI.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"YINI.js","sourceRoot":"","sources":["../src/YINI.ts"],"names":[],"mappings":"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"}

package/dist/core/astBuilder.d.ts

@@ -1,4 +1,4 @@
-import { AnnotationContext, AssignmentContext, Bad_memberContext, Bad_meta_textContext, Boolean_literalContext, Colon_list_declContext, DirectiveContext, ElementsContext, EolContext, List_literalContext, MemberContext, Meta_stmtContext, Null_literalContext, Number_literalContext, Object_literalContext, Object_memberContext, Object_membersContext, PrologContext, StmtContext, String_concatContext, String_literalContext, Terminal_stmtContext, ValueContext, YiniContext } from '../grammar/generated/YiniParser.js';
+import { AnnotationContext, AssignmentContext, Bad_memberContext, Bad_meta_textContext, Boolean_literalContext, DirectiveContext, ElementsContext, EolContext, List_literalContext, MemberContext, Meta_stmtContext, Null_literalContext, Number_literalContext, Object_literalContext, Object_memberContext, Object_membersContext, PrologContext, StmtContext, String_concatContext, String_literalContext, Terminal_stmtContext, ValueContext, YiniContext } from '../grammar/generated/YiniParser.js';
 import YiniParserVisitor from '../grammar/generated/YiniParserVisitor';
 import { ErrorDataHandler } from './errorDataHandler';
 import { IParseCoreOptions, IYiniAST, TSourceType } from './internalTypes';
@@ -28,6 +28,7 @@ export default class ASTBuilder<Result> extends YiniParserVisitor<Result> {
      * @param metaLineCount Provide the line-count here so the meta information can be updated accordingly.
      */
     constructor(errorHandler: ErrorDataHandler, options: IParseCoreOptions, sourceType: TSourceType, metaFileName: string | null);
+    private validateStrictTopLevelStructure;
     private hasDefinedSectionTitle;
     private setDefineSectionTitle;
     private extractStringParts;
@@ -166,12 +167,8 @@ export default class ASTBuilder<Result> extends YiniParserVisitor<Result> {
      */
     visitObject_member: (ctx: Object_memberContext) => any;
     /**
-     * Visit a parse tree produced by `YiniParser.colon_list_decl`.
-     * @param ctx the parse tree
-     * @grammarRule KEY WS? COLON (eol | WS+)* elements (eol | WS+)* eol
-     * @return the visitor result
+     * @note Colon list not supported any more since YINI Spec Package v1.0.0.rc4
      */
-    visitColon_list_decl: (ctx: Colon_list_declContext) => any;
     /**
      * Visit a parse tree produced by `YiniParser.string_concat`.
      * @param ctx the parse tree

package/dist/core/astBuilder.js

@@ -40,6 +40,7 @@ const env_1 = require("../config/env");
 const YiniParserVisitor_1 = __importDefault(require("../grammar/generated/YiniParserVisitor"));
 const extractSignificantYiniLine_1 = require("../parsers/extractSignificantYiniLine");
 const parseBoolean_1 = __importDefault(require("../parsers/parseBoolean"));
+const parseNull_1 = __importDefault(require("../parsers/parseNull"));
 const parseNumber_1 = __importDefault(require("../parsers/parseNumber"));
 // import parseNumber from '../parsers/parseNumber'
 const parseSectionHeader_1 = __importDefault(require("../parsers/parseSectionHeader"));
@@ -71,6 +72,7 @@ const makeScalarValue = (type, value = null, tag = undefined) => {
         case 'Undefined':
             return { type: 'Undefined', value: undefined, tag };
         default:
+            // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
             new errorDataHandler_1.ErrorDataHandler(_sourceType).pushOrBail(undefined, 'Fatal-Error', `No such type in makeValue(..), type: ${type}, value: ${value}`, 'Something in the code is done incorrectly in order for this to happen... :S');
     }
     return { type: 'Null', value: null, tag };
@@ -162,7 +164,6 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         // private meta_numOfChains = 0 // For stats.
         this.meta_maxLevel = 0; // For stats.
         this.mapSectionNamePaths = new Map();
-        // --- Private helper methods --------------------------------
         this.hasDefinedSectionTitle = (keyPath) => {
             return this.mapSectionNamePaths?.has(keyPath);
         };
@@ -229,17 +230,18 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         this.visitStmt = (ctx) => {
             const child = ctx.getChild(0);
             const ruleName = child?.constructor?.name ?? '';
+            // debugPrint('S0')
+            // const badHeaderWDotName = ctx.BAD_SECTION_HEAD_W_DOT_NAME()?.getText()
+            // if (badHeaderWDotName) {
+            //     console.log('QQQQQQQQ = ' + badHeaderWDotName)
+            // }
             if (ruleName.includes('EolContext'))
                 return this.visitEol?.(child);
             if (ruleName.includes('AssignmentContext'))
                 return this.visitAssignment?.(child);
-            if (ruleName.includes('Colon_list_declContext'))
-                return this.visitColon_list_decl?.(child);
             if (ruleName.includes('Meta_stmtContext'))
                 return this.visitMeta_stmt?.(child);
             (0, print_1.debugPrint)('S1');
-            // let headerAlt = child.getText?.() ?? ''
-            // let header = ctx.SECTION_HEAD()?.getText().trim() || ''
             let header = ctx.SECTION_HEAD()?.getText().trim() || '';
             // debugPrint('S2, lineAlt: >>>' + lineAlt + '<<<')
             (0, print_1.debugPrint)('S2, header: >>>' + header + '<<<');
@@ -423,9 +425,11 @@ class ASTBuilder extends YiniParserVisitor_1.default {
                         break;
                     case 'allow-with-warning':
                         valueNode = makeScalarValue('Null', null, 'Implicit null (empty value)');
+                        // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                         this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Warning', `Empty value treated as null for key '${resultKey}'.`, `An empty value after '=' was encountered. Per 'treatEmptyValueAsNull = allow-with-warning', interpreted as null.`, `If you intended null, write it explicitly: ${resultKey} = null. Otherwise provide a non-empty value or set 'treatEmptyValueAsNull' to 'disallow'.`);
                         break;
                     case 'disallow':
+                        // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                         this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', `Missing value for key '${resultKey}'`, `Expected a value after '=' but found none. Implicit nulls are disallowed by 'treatEmptyValueAsNull = disallow'.`, `Write 'null' explicitly (${resultKey} = null) if that is intended, or provide a concrete value.`);
                         return makeScalarValue('Undefined', undefined, 'Missing value already reported');
                 }
@@ -459,12 +463,14 @@ class ASTBuilder extends YiniParserVisitor_1.default {
                 )
             }*/
             if (!valueNode) {
+                // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                 this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid value', `Invalid value for key '${resultKey}' in member (<key> = <value> pair).`, `Got '${rawValue}', but expected a valid value/literal (string, number, boolean, null, list, or object). Optionally with a single leading minus sign '-'.`);
             }
             else if (valueNode.type === 'Undefined' &&
                 valueNode.tag !== 'Invalid string literal already reported' &&
                 valueNode.tag !== 'Missing value already reported' &&
                 valueNode.tag !== 'Parser syntax error already reported') {
+                // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                 this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid value', `Invalid value for key '${resultKey}' in member (<key> = <value> pair).`, `Got '${rawValue}', but expected a valid value/literal (string, number, boolean, null, list, or object). Optionally with a single leading minus sign '-'.`);
             }
             // It keeps the sentinel tags useful for control flow inside visitMember(..),
@@ -622,6 +628,7 @@ class ASTBuilder extends YiniParserVisitor_1.default {
                                 'Check that all escape sequences in the C-string are complete and valid.';
                         }
                     }
+                    // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                     this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', msgWhat, msgWhy, msgHint);
                     return makeScalarValue('Undefined', undefined, 'Invalid string literal already reported');
                 }
@@ -687,8 +694,14 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         // visitNull_literal?: (ctx: Null_literalContext) => Result
         this.visitNull_literal = (ctx) => {
             (0, print_1.debugPrint)('-> Entered visitNull_literal(..)');
-            (0, print_1.debugPrint)('raw = ' + ctx.getText());
-            return makeScalarValue('Null', null, 'Explicit Null');
+            // debugPrint('raw = ' + ctx.getText())
+            // return makeScalarValue('Null', null, 'Explicit Null')
+            const raw = ctx.getText();
+            (0, print_1.debugPrint)('raw:    "' + raw + '"');
+            const parsed = (0, parseNull_1.default)(raw);
+            (0, print_1.debugPrint)('parsed: "' + parsed + '"');
+            // Case-insensitive true/false/on/off/yes/no (Spec section, 8.1).
+            return makeScalarValue('Null', parsed, 'Explicit Null');
         };
         /**
          * Visit a parse tree produced by `YiniParser.list_literal`.
@@ -767,7 +780,8 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         this.visitObject_members = (ctx) => {
             (0, print_1.debugPrint)('-> Entered visitObject_members(..)');
             (0, print_1.debugPrint)('entries.length = ' + ctx?.object_member_list().length);
-            const entries = [];
+            // const entries: Array<{ k: string; v: TValueLiteral }> = []
+            const entries = {};
             ctx.object_member_list().forEach((member) => {
                 const { key, value } = this.visitObject_member(member);
                 (0, print_1.debugPrint)('   key = ' + key);
@@ -790,7 +804,7 @@ class ASTBuilder extends YiniParserVisitor_1.default {
             const rawValue = ctx.value().getText();
             const valueNode = ctx.value()
                 ? this.visitValue(ctx.value())
-                : makeScalarValue('Null', 'Implicit Null');
+                : makeScalarValue('Null', null, 'Implicit Null');
             (0, print_1.debugPrint)('  rawKey = ' + rawKey);
             (0, print_1.debugPrint)('     key = ' + key);
             (0, print_1.debugPrint)('rawValue = ' + rawValue);
@@ -806,30 +820,32 @@ class ASTBuilder extends YiniParserVisitor_1.default {
             return { key, value: valueNode };
         };
         /**
-         * Visit a parse tree produced by `YiniParser.colon_list_decl`.
-         * @param ctx the parse tree
-         * @grammarRule KEY WS? COLON (eol | WS+)* elements (eol | WS+)* eol
-         * @return the visitor result
+         * @note Colon list not supported any more since YINI Spec Package v1.0.0.rc4
          */
-        // visitColon_list_decl?: (ctx: ListAfterColonContext) => Result
-        this.visitColon_list_decl = (ctx) => {
-            (0, print_1.debugPrint)('-> Entered visitColon_list_decl(..)');
-            const key = ctx.getChild(0).getText();
-            (0, print_1.debugPrint)(`visitColon_list_decl(..): key = '${key}'`);
-            const elems = this.visitElements(ctx.elements());
-            const value = makeListValue(elems, 'From colon-list');
-            const current = this.sectionStack[this.sectionStack.length - 1];
-            // putMember(current, key, list, this.ast, this.onDuplicateKey)
-            this.putMember(this.errorHandler, ctx, current, key, value, 
-            // this.ast,
-            this.onDuplicateKey);
-            (0, print_1.debugPrint)('<- About to exit visitColon_list_decl(..)...');
-            if ((0, env_1.isDebug)()) {
-                console.log('List literal: (from a Colon-list)');
-                (0, print_1.printObject)(value);
-            }
-            return value;
-        };
+        // visitColon_list_decl = (ctx: Colon_list_declContext): any => {
+        //     debugPrint('-> Entered visitColon_list_decl(..)')
+        //     const key = ctx.getChild(0).getText()
+        //     debugPrint(`visitColon_list_decl(..): key = '${key}'`)
+        //     const elems = this.visitElements(ctx.elements())
+        //     const value = makeListValue(elems, 'From colon-list')
+        //     const current = this.sectionStack[this.sectionStack.length - 1]
+        //     // putMember(current, key, list, this.ast, this.onDuplicateKey)
+        //     this.putMember(
+        //         this.errorHandler!,
+        //         ctx,
+        //         current,
+        //         key,
+        //         value,
+        //         // this.ast,
+        //         this.onDuplicateKey,
+        //     )
+        //     debugPrint('<- About to exit visitColon_list_decl(..)...')
+        //     if (isDebug()) {
+        //         console.log('List literal: (from a Colon-list)')
+        //         printObject(value)
+        //     }
+        //     return value
+        // }
         /**
          * Visit a parse tree produced by `YiniParser.string_concat`.
          * @param ctx the parse tree
@@ -864,6 +880,7 @@ class ASTBuilder extends YiniParserVisitor_1.default {
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
+                // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                 this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Parse error in string', msg);
                 return undefined;
             }
@@ -921,6 +938,22 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         };
         this.sectionStack = [root];
     }
+    // --- Private helper methods --------------------------------
+    validateStrictTopLevelStructure() {
+        if (!this.isStrict)
+            return;
+        const numTopLevelSections = this.ast.root.children.length;
+        const numTopLevelMembers = this.ast.root.members.size;
+        if (numTopLevelMembers > 0) {
+            // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
+            this.errorHandler.pushOrBail(undefined, 'Syntax-Error', 'Top-level members are not allowed in strict mode.', 'Members were found outside the single required explicit top-level section.', 'Move all top-level members into the explicit top-level section, or parse the document in lenient mode.');
+        }
+        // Exactly one explicit top-level section in strict mode.
+        if (numTopLevelSections !== 1) {
+            // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
+            this.errorHandler.pushOrBail(undefined, 'Syntax-Error', 'Strict mode requires exactly one explicit top-level section.', `Found ${numTopLevelSections} explicit top-level section${numTopLevelSections === 1 ? '' : 's'}.`, 'Wrap the document in exactly one explicit top-level section and nest any additional sections beneath it.');
+        }
+    }
     extractStringParts(tokenText) {
         // Detect prefix
         let prefix = '';
@@ -1042,12 +1075,15 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         if (sec.members.has(key)) {
             switch (mode) {
                 case 'error':
+                    // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                     errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Hit a duplicate key in this section and scope', `Key '${key}' already exists in section '${sec.sectionName}' on level ${sec.level}.`);
                     break;
                 case 'warn-and-keep-first':
+                    // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                     errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Warning', `Hit a duplicate key (will keep first value) in this section and scope`, `Key '${key}' already exists in section '${sec.sectionName}' on level ${sec.level}.`);
                     return; // Keep first, don't overwrite.
                 case 'warn-and-overwrite':
+                    // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                     errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Warning', `Overwrote a duplicate key (will keep last value) in this section and scope`, `Key '${key}' was overwritten in section '${sec.sectionName}' on level ${sec.level}.`);
                     break; // Overwrite, replace value.
                 case 'keep-first':
@@ -1065,30 +1101,25 @@ class ASTBuilder extends YiniParserVisitor_1.default {
     // Public entry
     buildAST(ctx) {
         this.visitYini?.(ctx);
-        // The document terminator is optional by default.
-        // If the option `isRequireDocTerminator` is set to true,
-        // the '/END' terminator at the end of the document becomes required.
-        if (!this.ast.terminatorSeen &&
-            this.options.rules.requireDocTerminator === 'required') {
-            const msgWhat = `Missing '/END' at end of document (option requireDocTerminator is ${this.options.rules.requireDocTerminator}).`;
-            const msgWhy = `The terminator '/END' (case insensitive) is required and must appear at the end of the document.`;
-            const msgHint = `This is option can be overriden by the option requireDocTerminator.`;
+        // Strict-mode structural validation.
+        this.validateStrictTopLevelStructure();
+        const isMissingTerminator = !this.ast.terminatorSeen;
+        // In strict mode, the document terminator is required by default.
+        // However, the parse option `requireDocTerminator` is authoritative
+        // and may override that default behavior.
+        const terminatorPolicy = this.options.rules.requireDocTerminator;
+        if (isMissingTerminator && terminatorPolicy === 'required') {
             // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-            this.errorHandler.pushOrBail(undefined, 'Syntax-Error', msgWhat, msgWhy, msgHint);
+            this.errorHandler.pushOrBail(undefined, 'Syntax-Error', "Missing '/END' at end of document.", "The document terminator '/END' (case-insensitive) is required at the end of the document.", "Add '/END' as the final significant line, or change requireDocTerminator to 'optional' or 'warn-if-missing'.");
         }
-        else if (!this.ast.terminatorSeen &&
-            this.options.rules.requireDocTerminator === 'warn-if-missing') {
-            const msgWhat = `Missing '/END' at end of document (option requireDocTerminator is ${this.options.rules.requireDocTerminator}).`;
-            const msgWhy = `The terminator '/END' (case insensitive) might be missing at the end of the document.`;
-            const msgHint = `This is option can be overriden by the option requireDocTerminator.`;
+        else if (isMissingTerminator &&
+            terminatorPolicy === 'warn-if-missing') {
             // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-            this.errorHandler.pushOrBail(undefined, 'Syntax-Warning', msgWhat, msgWhy, msgHint);
+            this.errorHandler.pushOrBail(undefined, 'Syntax-Warning', "Missing '/END' at end of document.", "The document terminator '/END' (case-insensitive) appears to be missing at the end of the document.", "Add '/END' as the final significant line, or change requireDocTerminator to 'optional'.");
         }
-        // Note: Below is important for error checking as well as for meta data.
         this.ast.numOfSections = this.mapSectionNamePaths.size;
         this.ast.numOfMembers = this._numOfMembers;
         if (this.options.isIncludeMeta) {
-            // Attach collected meta information.
             this.ast.maxDepth = this.meta_maxLevel;
             this.ast.sectionNamePaths = [...this.mapSectionNamePaths.keys()];
         }