yini-parser 1.5.0 → 1.6.1

package/dist/core/errorDataHandler.d.ts

@@ -1,6 +1,28 @@
 import { IssuePayload } from '../types';
 import { IErrorLocationInput, TBailSensitivityLevel, TIssueType, TSubjectType } from './internalTypes';
 export declare const toErrorLocation: (ctx: any) => IErrorLocationInput | undefined;
+export interface YiniParseErrorDetails {
+    type: TIssueType;
+    typeKey: string;
+    sourceType: TSubjectType;
+    fileName?: string;
+    line?: number;
+    column?: number;
+    message: string;
+    advice?: string;
+    hint?: string;
+}
+export declare class YiniParseError extends Error {
+    readonly type: TIssueType;
+    readonly typeKey: string;
+    readonly sourceType: TSubjectType;
+    readonly fileName?: string;
+    readonly line?: number;
+    readonly column?: number;
+    readonly advice?: string;
+    readonly hint?: string;
+    constructor(details: YiniParseErrorDetails);
+}
 /**
  * This class handles all error/notice reporting and processes exit/throwing.
  */
@@ -8,6 +30,7 @@ export declare class ErrorDataHandler {
     private readonly subjectType;
     private readonly fileName;
     private readonly persistThreshold;
+    private readonly isDiagnosticOutputEnabled;
     private readonly isQuiet;
     private readonly isSilent;
     private readonly isThrowOnError;
@@ -30,10 +53,12 @@ export declare class ErrorDataHandler {
             - Level 1 = abort on errors only
             - Level 2 = abort even on warnings
      */
-    constructor(subjectType: TSubjectType, fileName?: string | undefined, bailSensitivityLevel?: TBailSensitivityLevel, isQuiet?: boolean, // Reduce output (show only errors, does not effect warnings and etc. in meta data).
+    constructor(subjectType: TSubjectType, fileName?: string | undefined, bailSensitivityLevel?: TBailSensitivityLevel, isDiagnosticOutputEnabled?: boolean, // Opt in to writing diagnostics to stderr.
+    isQuiet?: boolean, // When diagnostic output is enabled, show errors only.
     isSilent?: boolean, // Suppress all output (even errors, exit code only).
     isThrowOnError?: boolean);
     private makeIssue;
+    private throwParseError;
     /**
      * After pushing processing may continue or exit, depending on the error
      * and/or the bail threshold (that can be optionally set by the user).
@@ -50,6 +75,9 @@ export declare class ErrorDataHandler {
      */
     pushOrBail(locInput: IErrorLocationInput | undefined, type: TIssueType, msgWhat: string, msgWhy?: string, msgHint?: string): void;
     private formatSignificantMessageLine;
+    private shouldEmitDiagnostics;
+    private shouldEmitNonErrors;
+    private emitDiagnosticToStderr;
     private emitFatalError;
     private emitInternalError;
     private emitSyntaxError;

package/dist/core/errorDataHandler.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ErrorDataHandler = exports.toErrorLocation = void 0;
+exports.ErrorDataHandler = exports.YiniParseError = exports.toErrorLocation = void 0;
 // src/core/errorDataHandler.ts
 const env_1 = require("../config/env");
 const print_1 = require("../utils/print");
@@ -29,6 +29,66 @@ const issueTitle = [
     'Notice:',
     'Info:',
 ];
+class YiniParseError extends Error {
+    constructor(details) {
+        super(formatThrownMessage(details));
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = getErrorName(details.type);
+        this.type = details.type;
+        this.typeKey = details.typeKey;
+        this.sourceType = details.sourceType;
+        this.fileName = details.fileName;
+        this.line = details.line;
+        this.column = details.column;
+        this.advice = details.advice;
+        this.hint = details.hint;
+        // Node prints `error.stack` for uncaught errors. Keep parser failures
+        // focused on the user's document instead of internal parser frames.
+        this.stack = `${this.name}: ${this.message}`;
+    }
+}
+exports.YiniParseError = YiniParseError;
+const getErrorName = (type) => {
+    switch (type) {
+        case 'Syntax-Error':
+        case 'Syntax-Warning':
+            return 'YiniSyntaxError';
+        case 'Internal-Error':
+        case 'Fatal-Error':
+            return 'YiniInternalError';
+        default:
+            return 'YiniParseError';
+    }
+};
+const formatThrownMessage = (details) => {
+    const lines = [];
+    const location = formatThrownLocation(details);
+    const title = details.type.replace(/-/g, ' ');
+    lines.push(location
+        ? `${title} in ${location}: ${details.message}`
+        : `${title}: ${details.message}`);
+    if (details.advice) {
+        lines.push(details.advice);
+    }
+    if (details.hint) {
+        lines.push(`Hint: ${details.hint}`);
+    }
+    return lines.join('\n');
+};
+const formatThrownLocation = (details) => {
+    if (details.sourceType === 'None/Ignore')
+        return '';
+    let location = details.sourceType === 'File'
+        ? details.fileName || 'YINI file'
+        : 'inline YINI content';
+    if (details.line !== undefined) {
+        location += `:${details.line}`;
+        if (details.column !== undefined) {
+            location += `:${details.column}`;
+        }
+    }
+    return location;
+};
 /**
  * This class handles all error/notice reporting and processes exit/throwing.
  */
@@ -42,7 +102,8 @@ class ErrorDataHandler {
             - Level 1 = abort on errors only
             - Level 2 = abort even on warnings
      */
-    constructor(subjectType, fileName = undefined, bailSensitivityLevel = '1-Abort-on-Errors', isQuiet = false, // Reduce output (show only errors, does not effect warnings and etc. in meta data).
+    constructor(subjectType, fileName = undefined, bailSensitivityLevel = '1-Abort-on-Errors', isDiagnosticOutputEnabled = false, // Opt in to writing diagnostics to stderr.
+    isQuiet = false, // When diagnostic output is enabled, show errors only.
     isSilent = false, // Suppress all output (even errors, exit code only).
     isThrowOnError = false) {
         this.errors = [];
@@ -58,6 +119,7 @@ class ErrorDataHandler {
         this.subjectType = subjectType;
         this.fileName = fileName;
         this.persistThreshold = bailSensitivityLevel;
+        this.isDiagnosticOutputEnabled = isDiagnosticOutputEnabled;
         this.isQuiet = isQuiet;
         this.isSilent = isSilent;
         this.isThrowOnError = isThrowOnError;
@@ -75,6 +137,19 @@ class ErrorDataHandler {
         (0, env_1.isDebug)() && console.log(issue);
         return issue;
     }
+    throwParseError(type, issue, msgWhatInclLineNum) {
+        throw new YiniParseError({
+            type,
+            typeKey: issue.typeKey,
+            sourceType: this.subjectType,
+            fileName: this.fileName,
+            line: issue.line,
+            column: issue.column,
+            message: msgWhatInclLineNum,
+            advice: issue.advice,
+            hint: issue.hint,
+        });
+    }
     /**
      * After pushing processing may continue or exit, depending on the error
      * and/or the bail threshold (that can be optionally set by the user).
@@ -118,13 +193,16 @@ class ErrorDataHandler {
             lineNum: lineNum || 0, // 1-based, if n/a use 0.
             colNum: colNum || 0, // 1-based, if n/a use 0.
         };
-        if (!this.isSilent) {
-            console.log(); // Print an empty line before outputting message.
+        if (this.shouldEmitDiagnostics()) {
+            console.error(); // Print an empty line before outputting message.
         }
         switch (type) {
             case 'Internal-Error':
                 this.numInternalErrors++;
-                this.errors.push(this.makeIssue(lineNum, colNum, type, msgWhat, msgWhy, msgHint));
+                {
+                    const issue = this.makeIssue(lineNum, colNum, type, msgWhat, msgWhy, msgHint);
+                    this.errors.push(issue);
+                }
                 this.emitInternalError(loc, msgWhatInclLineNum, msgWhy, msgHint);
                 if (this.persistThreshold === '1-Abort-on-Errors' ||
                     this.persistThreshold === '2-Abort-Even-on-Warnings') {
@@ -132,16 +210,16 @@ class ErrorDataHandler {
                         (0, print_1.debugPrint)('Skipped throwing');
                     }
                     else {
-                        const thrownMsg = msgWhy
-                            ? `Internal-Error: ${msgWhatInclLineNum}. ${msgWhy}`
-                            : `Internal-Error: ${msgWhatInclLineNum}`;
-                        throw new Error(thrownMsg);
+                        this.throwParseError(type, this.errors[this.errors.length - 1], msgWhatInclLineNum);
                     }
                 }
                 break;
             case 'Syntax-Error':
                 this.numSyntaxErrors++;
-                this.errors.push(this.makeIssue(lineNum, colNum, type, msgWhat, msgWhy, msgHint));
+                {
+                    const issue = this.makeIssue(lineNum, colNum, type, msgWhat, msgWhy, msgHint);
+                    this.errors.push(issue);
+                }
                 this.emitSyntaxError(loc, msgWhatInclLineNum, msgWhy, msgHint);
                 if (this.persistThreshold === '1-Abort-on-Errors' ||
                     this.persistThreshold === '2-Abort-Even-on-Warnings') {
@@ -149,16 +227,16 @@ class ErrorDataHandler {
                         (0, print_1.debugPrint)('Skipped throwing');
                     }
                     else {
-                        const thrownMsg = msgWhy
-                            ? `Syntax-Error: ${msgWhatInclLineNum}. ${msgWhy}`
-                            : `Syntax-Error: ${msgWhatInclLineNum}`;
-                        throw new Error(thrownMsg);
+                        this.throwParseError(type, this.errors[this.errors.length - 1], msgWhatInclLineNum);
                     }
                 }
                 break;
             case 'Syntax-Warning':
                 this.numSyntaxWarnings++;
-                this.warnings.push(this.makeIssue(lineNum, colNum, type, msgWhat, msgWhy, msgHint));
+                {
+                    const issue = this.makeIssue(lineNum, colNum, type, msgWhat, msgWhy, msgHint);
+                    this.warnings.push(issue);
+                }
                 if (!this.isQuiet) {
                     this.emitSyntaxWarning(loc, msgWhatInclLineNum, msgWhy, msgHint);
                 }
@@ -167,10 +245,7 @@ class ErrorDataHandler {
                         (0, print_1.debugPrint)('Skipped throwing');
                     }
                     else {
-                        const thrownMsg = msgWhy
-                            ? `Syntax-Error: ${msgWhatInclLineNum}. ${msgWhy}`
-                            : `Syntax-Error: ${msgWhatInclLineNum}`;
-                        throw new Error(thrownMsg);
+                        this.throwParseError(type, this.warnings[this.warnings.length - 1], msgWhatInclLineNum);
                     }
                 }
                 break;
@@ -198,10 +273,7 @@ class ErrorDataHandler {
                 // In test, throw an error instead of bailing/exiting.
                 // IMPORTANT: Never exit with exit code since this is a library!
                 {
-                    const thrownMsg = msgWhy
-                        ? `Internal-Error: ${msgWhatInclLineNum}. ${msgWhy}`
-                        : `Internal-Error: ${msgWhatInclLineNum}`;
-                    throw new Error(thrownMsg);
+                    this.throwParseError('Internal-Error', this.errors[this.errors.length - 1], msgWhatInclLineNum);
                 }
         }
     }
@@ -229,68 +301,53 @@ class ErrorDataHandler {
             }
         }
     }
-    /*
-     * - error/warning → console.error / console.warn
-     * - notice/info → console.log / console.info
-     */
+    shouldEmitDiagnostics() {
+        return this.isDiagnosticOutputEnabled && !this.isSilent;
+    }
+    shouldEmitNonErrors() {
+        return this.shouldEmitDiagnostics() && !this.isQuiet;
+    }
+    emitDiagnosticToStderr(write, messageHeader, msgWhat = '', msgWhy = '', msgHint = '') {
+        write(messageHeader);
+        msgWhat && write(msgWhat);
+        msgWhy && write(msgWhy);
+        msgHint && write(msgHint);
+        write();
+    }
     emitFatalError(loc, msgWhat = 'Something went wrong!', msgWhy = '', msgHint = '') {
         const messageHeader = this.formatSignificantMessageLine(loc, issueTitle[0]);
-        if (!this.isSilent) {
-            console.error(messageHeader); // Print the issue title.
-            msgWhat && console.log(msgWhat);
-            msgWhy && console.log(msgWhy);
-            msgHint && console.log(msgHint);
-            console.log(); // Emit an empty line before outputting message.
+        if (this.shouldEmitDiagnostics()) {
+            this.emitDiagnosticToStderr(console.error.bind(console), messageHeader, msgWhat, msgWhy, msgHint);
         }
     }
     emitInternalError(loc, msgWhat = 'Something went wrong!', msgWhy = '', msgHint = '') {
         const messageHeader = this.formatSignificantMessageLine(loc, issueTitle[1]);
-        if (!this.isSilent) {
-            console.error(messageHeader); // Print the issue title.
-            msgWhat && console.log(msgWhat);
-            msgWhy && console.log(msgWhy);
-            msgHint && console.log(msgHint);
-            console.log(); // Emit an empty line before outputting message.
+        if (this.shouldEmitDiagnostics()) {
+            this.emitDiagnosticToStderr(console.error.bind(console), messageHeader, msgWhat, msgWhy, msgHint);
         }
     }
     emitSyntaxError(loc, msgWhat, msgWhy = '', msgHint = '') {
         const messageHeader = this.formatSignificantMessageLine(loc, issueTitle[2]);
-        if (!this.isSilent) {
-            console.error(messageHeader); // Print the issue title.
-            msgWhat && console.log(msgWhat);
-            msgWhy && console.log(msgWhy);
-            msgHint && console.log(msgHint);
-            console.log(); // Emit an empty line before outputting message.
+        if (this.shouldEmitDiagnostics()) {
+            this.emitDiagnosticToStderr(console.error.bind(console), messageHeader, msgWhat, msgWhy, msgHint);
         }
     }
     emitSyntaxWarning(loc, msgWhat, msgWhy = '', msgHint = '') {
         const messageHeader = this.formatSignificantMessageLine(loc, issueTitle[3]);
-        if (!this.isQuiet && !this.isSilent) {
-            console.warn(messageHeader); // Print the issue title.
-            msgWhat && console.log(msgWhat);
-            msgWhy && console.log(msgWhy);
-            msgHint && console.log(msgHint);
-            console.log(); // Emit an empty line before outputting message.
+        if (this.shouldEmitNonErrors()) {
+            this.emitDiagnosticToStderr(console.warn.bind(console), messageHeader, msgWhat, msgWhy, msgHint);
         }
     }
     emitNotice(loc, msgWhat, msgWhy = '', msgHint = '') {
         const messageHeader = this.formatSignificantMessageLine(loc, issueTitle[4]);
-        if (!this.isQuiet && !this.isSilent) {
-            console.log(messageHeader); // Print the issue title.
-            msgWhat && console.log(msgWhat);
-            msgWhy && console.log(msgWhy);
-            msgHint && console.log(msgHint);
-            console.log(); // Emit an empty line before outputting message.
+        if (this.shouldEmitNonErrors()) {
+            this.emitDiagnosticToStderr(console.error.bind(console), messageHeader, msgWhat, msgWhy, msgHint);
         }
     }
     emitInfo(loc, msgWhat, msgWhy = '', msgHint = '') {
         const messageHeader = this.formatSignificantMessageLine(loc, issueTitle[5]);
-        if (!this.isQuiet && !this.isSilent) {
-            console.info(messageHeader); // Print the issue title.
-            msgWhat && console.log(msgWhat);
-            msgWhy && console.log(msgWhy);
-            msgHint && console.log(msgHint);
-            console.log(); // Emit an empty line before outputting message.
+        if (this.shouldEmitNonErrors()) {
+            this.emitDiagnosticToStderr(console.error.bind(console), messageHeader, msgWhat, msgWhy, msgHint);
         }
     }
     getNumOfAllMessages() {

package/dist/core/internalTypes.d.ts

@@ -70,7 +70,7 @@ export type TObjectValue = {
     entries: Readonly<Record<string, TValueLiteral>>;
     tag: string | undefined;
 };
-type TStringKind = 'raw' | 'classic' | 'hyper' | 'triple-raw' | 'triple-classic';
+type TStringKind = 'raw' | 'classic' | 'triple-raw' | 'triple-classic';
 export interface IParsedStringInput {
     strKind: TStringKind;
     value: string;
@@ -82,6 +82,13 @@ export interface IErrorLocationInput {
     endColumn?: number;
 }
 export type TIssueType = 'Fatal-Error' | 'Internal-Error' | 'Syntax-Error' | 'Syntax-Warning' | 'Notice' | 'Info';
+export interface IPreflightIssue {
+    locInput: IErrorLocationInput | undefined;
+    type: TIssueType;
+    msgWhat: string;
+    msgWhy?: string;
+    msgHint?: string;
+}
 interface IMetaBaseInfo {
     sourceType: TSourceType;
     fileName: string | undefined;
@@ -96,6 +103,7 @@ export interface IRuntimeInfo extends IMetaBaseInfo {
     timeIoMs: number | null;
     preferredBailSensitivity: null | PreferredFailLevel;
     sha256: string | null;
+    preflightIssues: IPreflightIssue[];
 }
 export interface IParseCoreOptions {
     rules: IParseRuleOptions;
@@ -104,6 +112,7 @@ export interface IParseCoreOptions {
     isWithDiagnostics: boolean;
     isWithTiming: boolean;
     isKeepUndefinedInMeta: boolean;
+    isDiagnosticOutputEnabled: boolean;
     isQuiet: boolean;
     isSilent: boolean;
     isThrowOnError: boolean;

package/dist/core/objectBuilder.js

@@ -17,6 +17,7 @@ const print_1 = require("../utils/print");
  *
  * @note All `tag` fields MUST be ignored.
  */
+// src/core/objectBuilder.ts
 const astToObject = (ast, errorHandler) => {
     (0, print_1.debugPrint)('-> constructFinalObject(..)');
     const out = {};
@@ -28,12 +29,12 @@ const astToObject = (ast, errorHandler) => {
     }
     // 2) Mount explicit top-level sections directly onto result.
     for (const child of ast.root.children) {
-        // Collision: a lenient orphan member already used this name.
         if (Object.prototype.hasOwnProperty.call(out, child.sectionName)) {
             errorHandler.pushOrBail(undefined, 'Syntax-Error', `Name collision between orphan member and section '${child.sectionName}'`, `The name '${child.sectionName}' is already used by a top-level member outside any explicit section and cannot also be used as a top-level section name.`, `Rename either the orphan member or the section to avoid the collision.`);
             continue;
         }
-        define(out, child.sectionName, sectionToObject(child));
+        // define(out, child.sectionName, sectionToObject(child))
+        define(out, child.sectionName, sectionToObject(child, errorHandler));
     }
     return out;
 };
@@ -42,15 +43,29 @@ exports.astToObject = astToObject;
  * Convert a section (members + nested sections) to a plain object,
  * preserving insertion order.
  */
-const sectionToObject = (node) => {
+// const sectionToObject = (node: IYiniSection): Record<string, unknown> => {
+//     const obj: Record<string, unknown> = {}
+//     // 1) Members (Map preserves insertion order).
+//     for (const [key, val] of node.members) {
+//         define(obj, key, literalToJS(val))
+//     }
+//     // 2) Nested sections (array order preserved).
+//     for (const child of node.children) {
+//         define(obj, child.sectionName, sectionToObject(child))
+//     }
+//     return obj
+// }
+const sectionToObject = (node, errorHandler) => {
     const obj = {};
-    // 1) Members (Map preserves insertion order).
     for (const [key, val] of node.members) {
         define(obj, key, literalToJS(val));
     }
-    // 2) Nested sections (array order preserved).
     for (const child of node.children) {
-        define(obj, child.sectionName, sectionToObject(child));
+        if (Object.prototype.hasOwnProperty.call(obj, child.sectionName)) {
+            errorHandler.pushOrBail(undefined, 'Syntax-Error', `Name collision between member and subsection '${child.sectionName}'`, `The name '${child.sectionName}' is already used by a member in section '${node.sectionName}' and cannot also be used as a subsection name.`, 'Rename either the member or the subsection.');
+            continue;
+        }
+        define(obj, child.sectionName, sectionToObject(child, errorHandler));
     }
     return obj;
 };

package/dist/core/options/defaultParserOptions.d.ts

@@ -7,11 +7,12 @@ export declare const getDefaultUserOptions: (mode: TParserMode) => {
     onDuplicateKey: import("../../types").OnDuplicateKey;
     requireDocTerminator: import("../../types").DocumentTerminatorRule;
     treatEmptyValueAsNull: import("../../types").EmptyValueRule;
+    logDiagnostics: boolean;
     quiet: boolean;
     silent: boolean;
     throwOnError: boolean;
-    strictMode: boolean;
     failLevel: import("../../types").PreferredFailLevel;
     includeMetadata: boolean;
+    strictMode: boolean;
 };
-export type TNormalizedUserOptions = Required<Pick<ParseOptions, 'strictMode' | 'failLevel' | 'includeMetadata' | 'includeDiagnostics' | 'includeTiming' | 'preserveUndefinedInMeta' | 'onDuplicateKey' | 'requireDocTerminator' | 'treatEmptyValueAsNull' | 'quiet' | 'silent' | 'throwOnError'>>;
+export type TNormalizedUserOptions = Required<Pick<ParseOptions, 'strictMode' | 'failLevel' | 'includeMetadata' | 'includeDiagnostics' | 'includeTiming' | 'preserveUndefinedInMeta' | 'onDuplicateKey' | 'requireDocTerminator' | 'treatEmptyValueAsNull' | 'logDiagnostics' | 'quiet' | 'silent' | 'throwOnError'>>;

package/dist/core/options/defaultParserOptions.js

@@ -14,7 +14,8 @@ const BASE_DEFAULTS = {
     onDuplicateKey: 'error',
     requireDocTerminator: 'optional',
     treatEmptyValueAsNull: 'allow-with-warning',
-    quiet: false, // Suppress warnings in console (does not affect warnings in meta data).
+    logDiagnostics: false,
+    quiet: false, // When logDiagnostics is true, suppress warnings in stderr output.
     silent: false,
     //@todo: Change default throwOnError to false
     throwOnError: true, // Will throw on first parse error encountered.

package/dist/core/options/optionsFunctions.js

@@ -15,13 +15,16 @@ const toCoreOptions = (userOpts, bailLevel) => {
             treatEmptyValueAsNull: userOpts.treatEmptyValueAsNull,
         },
         bailSensitivity: level,
-        isIncludeMeta: userOpts.includeMetadata,
+        isIncludeMeta: userOpts.includeMetadata ||
+            userOpts.includeDiagnostics ||
+            userOpts.includeTiming,
         // isWithDiagnostics: isDev() || isDebug() || userOpts.includeDiagnostics,
         isWithDiagnostics: userOpts.includeDiagnostics,
         // isWithTiming: isDev() || isDebug() || userOpts.includeTiming,
         isWithTiming: userOpts.includeTiming,
         // isKeepUndefinedInMeta: isDebug() || userOpts.preserveUndefinedInMeta,
         isKeepUndefinedInMeta: userOpts.preserveUndefinedInMeta,
+        isDiagnosticOutputEnabled: userOpts.logDiagnostics,
         isQuiet: userOpts.quiet, // Suppress warnings, etc.
         isSilent: userOpts.silent,
         isThrowOnError: userOpts.throwOnError,
@@ -41,6 +44,7 @@ const isOptionsObjectForm = (v) => {
             'onDuplicateKey' in v ||
             'requireDocTerminator' in v ||
             'treatEmptyValueAsNull' in v ||
+            'logDiagnostics' in v ||
             'quiet' in v ||
             'silent' in v ||
             'throwOnError' in v));

package/dist/core/pipeline/pipeline.js

@@ -63,12 +63,21 @@ const runPipeline = (yiniContent, coreOptions, runtimeInfo, _meta_userOpts) => {
     //     default:
     //         persistThreshold = '2-Abort-Even-on-Warnings'
     // }
-    const errorHandler = new errorDataHandler_1.ErrorDataHandler(runtimeInfo.sourceType, runtimeInfo.fileName, coreOptions.bailSensitivity, coreOptions.isQuiet, coreOptions.isSilent, coreOptions.isThrowOnError);
-    if (yiniContent.trim() === '') {
-        const isFileSourceType = runtimeInfo?.sourceType === 'File';
-        // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-        errorHandler.pushOrBail(undefined, 'Syntax-Error', 'Empty YINI document.', `The input is blank or contains only whitespace in the ${isFileSourceType ? 'YINI file' : 'YINI inline content'}.`, `Tip: Add at least one section '^ SectionName' or a key-value pair 'key = value' to make it a valid YINI file.`);
+    const errorHandler = new errorDataHandler_1.ErrorDataHandler(runtimeInfo.sourceType, runtimeInfo.fileName, coreOptions.bailSensitivity, coreOptions.isDiagnosticOutputEnabled, coreOptions.isQuiet, coreOptions.isSilent, coreOptions.isThrowOnError);
+    for (const issue of runtimeInfo.preflightIssues) {
+        errorHandler.pushOrBail(issue.locInput, issue.type, issue.msgWhat, issue.msgWhy, issue.msgHint);
     }
+    // if (yiniContent.trim() === '') {
+    //     const isFileSourceType: boolean = runtimeInfo?.sourceType === 'File'
+    //     // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
+    //     errorHandler.pushOrBail(
+    //         undefined,
+    //         'Syntax-Error',
+    //         'Empty YINI document.',
+    //         `The input is blank or contains only whitespace in the ${isFileSourceType ? 'YINI file' : 'YINI inline content'}.`,
+    //         `Tip: Add at least one section '^ SectionName' or a key-value pair 'key = value' to make it a valid YINI file.`,
+    //     )
+    // }
     //---------------------------------------------
     // Note: Only computed when isWithTiming.
     let timeStartMs = 0;
@@ -140,8 +149,18 @@ const runPipeline = (yiniContent, coreOptions, runtimeInfo, _meta_userOpts) => {
     const builder = new astBuilder_1.default(errorHandler, coreOptions, runtimeInfo.sourceType, runtimeInfo.fileName || null);
     const ast = builder.buildAST(parseTree);
     if (ast.numOfMembers === 0 && ast.numOfSections === 0) {
-        // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-        errorHandler.pushOrBail(undefined, 'Syntax-Error', 'No meaningful content.', `No sections or members found in the ${ast.sourceType === 'File' ? 'YINI file' : 'YINI inline content'}.`, `${ast.sourceType === 'File' ? 'A valid YINI file' : 'Any valid YINI inline content'} must contain at least one section '^ SectionName' or a key–value pair 'key = value' to make it a valid YINI file.`);
+        // Lenient mode: empty document is allowed, but warning.
+        // Strict mode: empty document is invalid, error.
+        const sourceLabel = ast.sourceType === 'File' ? 'YINI file' : 'YINI inline content';
+        const sourceRequirement = ast.sourceType === 'File'
+            ? 'A valid YINI file must contain at least one section, for example: ^ SectionName, or a key-value pair, for example: key = value.'
+            : 'Valid YINI inline content must contain at least one section, for example: ^ SectionName, or a key-value pair, for example: key = value.';
+        if (ast.isStrict === true) {
+            errorHandler.pushOrBail(undefined, 'Syntax-Error', 'Empty YINI document.', `The ${sourceLabel} contains no meaningful content.`, sourceRequirement);
+        }
+        else {
+            errorHandler.pushOrBail(undefined, 'Syntax-Warning', 'Empty YINI document.', `The ${sourceLabel} contains no meaningful content.`, sourceRequirement);
+        }
     }
     if ((0, env_1.isDebug)()) {
         console.log();
@@ -177,11 +196,10 @@ const runPipeline = (yiniContent, coreOptions, runtimeInfo, _meta_userOpts) => {
     (0, env_1.isDebug)() && console.debug(finalJSResult);
     (0, print_1.debugPrint)();
     if (coreOptions.rules.initialMode === 'strict') {
-        // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-        errorHandler.pushOrBail(undefined, 'Syntax-Warning', 'Warning: Strict initialMode is not yet fully implemented.', 'Some validation rules may still be missing or incomplete.');
         if (coreOptions.bailSensitivity === '0-Ignore-Errors') {
-            // IMPORTANT: If "silent" option is set, do not log anything to console!
-            if (!coreOptions.isQuiet && !coreOptions.isSilent) {
+            if (coreOptions.isDiagnosticOutputEnabled &&
+                !coreOptions.isQuiet &&
+                !coreOptions.isSilent) {
                 console.warn(`Warning: The initial mode was set to strict mode, but fail level is set to 'ignore-errors'. This combination is contradictory and might be a mistake.`);
             }
         }
@@ -208,7 +226,8 @@ const runPipeline = (yiniContent, coreOptions, runtimeInfo, _meta_userOpts) => {
     const constructedMetadata = (0, resultMetadataBuilder_1.buildResultMetadata)(params);
     (0, print_1.debugPrint)('getNumOfErrors(): ' + errorHandler.getNumOfErrors());
     // Print a summary line at the end if any errors or warnings.
-    if (!coreOptions.isQuiet && !coreOptions.isSilent) {
+    if (coreOptions.isDiagnosticOutputEnabled &&
+        !coreOptions.isSilent) {
         const errors = errorHandler.getNumOfErrors();
         const warnings = errorHandler.getNumOfWarnings();
         // Notes: