yini-parser 1.0.2-beta → 1.1.0-beta

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # CHANGELOG
 
+## --dev/uppcoming--
+
+## 1.1.0-beta - 2025 Sep
+### Parser
+- **Reimplemented parser from scratch** (`core/ASTBuilder.ts`) using the refactored grammar for a much cleaner and more maintainable design.  
+- **Build logic reimplemented** (`core/objectBuilder.ts`) for improved reliability and consistency.  
+- **Error reporting enhanced** to be more user-friendly and informative.  
+- **Fixed bug sometimes wrong line** Sometimes incorrect line number in error messages are now reported accurately.
+- Renamed option `bailSensitivity` to a more shorter and user-friendly name `failLevel`.
+- **Extended `parse` and `parseFile` methods** to support an options-object form.  
+  Example:
+  ```ts
+  const config= YINI.parse(yini, {
+            strictMode: false,
+            failLevel: 'auto',
+            includeMetaData: false,
+            requireDocTerminator: false,
+        })  
+  ```  
+### Specification Alignment
+- Updated to follow the **latest YINI specification (v1.0.0-rc.3)**.  
+  - Document terminator `/END` is now optional in both lenient and strict mode.
+### Meta Data
+- The optional returned **meta data structure** has been redesigned.  
+  - Now includes improved organization.  
+  - **Timing support** added for detailed performance insight.
+  - Grouping with **source**, **structure**, **diagnostics**, etc.
+
 ## 1.0.2-beta - 2025 Aug
 - Fixed issues with floats, including negative and exponential numbers with new test files here: `tests/fixed-issues/issue-32/*`
 - Fixed an issue where parseFile(..) did not output a warning when parsing a file missing a newline at EOF. Plus added test cases to check that it is fixed (in `tests/fixed-issues/issue-30`).

package/README.md

@@ -21,7 +21,7 @@ YINI (Yet another INI): YINI is a configuration format designed for readability
 
 ---
 
-## YINI Parser – TypeScript
+## YINI Parser – (source code in TypeScript)
 
 > 🚧 This package is in **beta**. The core API is stabilizing, some more advanced features may still change. Feedback and bug reports are welcome!
 
@@ -58,20 +58,25 @@ YINI is a simple, human-friendly configuration format inspired by INI and JSON.
 
 ## Quick Start
 
-A minimal example using YINI in TypeScript:
+A small example using YINI in TypeScript/JavaScript:
 ```ts
 import YINI from 'yini-parser'
 
 const config = YINI.parse(`
-^ App
-name     = 'My Title'    // App display name.
-items    = 25
-darkMode = true
-
-    // Sub-section of App.
-    ^^ Special
-    primaryColor = #336699
-    isCaching = false
+    // YINI is a simple, human-readable configuration file format.
+
+    // Note: In YINI, spaces and tabs don't change meaning - 
+    // indentation is just for readability.
+
+    ^ App                      // Definition of section (group) "App" 
+      name     = 'My Title'    // Keys and values are written as key = value
+      items    = 25
+      darkMode = true          // "ON" and "YES" works too
+
+        // Sub-section of the "App" section
+        ^^ Special
+           primaryColor = #336699   // Hex number format
+           isCaching    = false     // "OFF" and "NO" works too
 `)
 
 // To parse from a file instead:
@@ -89,15 +94,15 @@ My Title
 false
 
 {
-  App: {
-    name: 'My Title',
-    items: 25,
-    darkMode: true,
-    Special: { 
-      primaryColor: 3368601,
-      isCaching: false
+    App: {
+        name: 'My Title',
+        items: 25,
+        darkMode: true,
+        Special: { 
+            primaryColor: 3368601,
+            isCaching: false
+        }
     }
-  }
 }
 ```
 
@@ -229,45 +234,44 @@ These examples are also included in the npm package.
 
 ---
 
-## Advanced Example
+## Bigger Example
 
 ```js
 const YINI = require('yini-parser').default; // Or: import YINI from 'yini-parser';
 
 const config = YINI.parse(`
-    /*
-        This is a multi-line block comment.
+    // This is a comment in YINI
+    // YINI is a simple, human-readable configuration file format.
+
+    // Note: In YINI, spaces and tabs don't change meaning - indentation is just
+    // for readability.
+
+    /*  This is a block comment
+
+        In YINI, section headers use repeated characters "^" at the start to
+        show their level: (Section header names are case-sensitive.)
+
+        ^ SectionLevel1
+        ^^ SectionLevel2
+        ^^^ SectionLevel3
     */
 
-    @yini
+    ^ App                           // Definition of section (group) "App" 
+      title = 'My App'
+      items = 25
+      debug = ON                    // "true" and "YES" works too
 
-    ^ App
-    name = "Nested Example"
-    version = "1.0.0"
-    debug = OFF  // This is a comment.
-
-        # Database settings.
-        ^^ Database
-        host = "db.example.com"
-        port = 3306
-        user = "appuser"
-        --password = "dbpassword"  # Disabled line due to --.
-        //password = "dbpassword"  # Not sure yet about this pw.
-        password = "dbpassword"  # Keep this secret.
-
-            // Commenting with slashes works too.
-            ^^^ Pool
-            min = 2
-            max = 10
-            idleTimeout = 300
-
-        /* Block comment on a single line. */
-        ^^ Logging
-        level = "info"
-        logToFile = ON # This is a comment.
-        filePath = "./logs/app.log"
+    ^ Server                        // Definition of section (group) "Server"
+      host = 'localhost'
+      port = 8080
+      useTLS = OFF                  // "false" and "NO" works too
+
+        // Sub-section of "Server"
+        ^^ Login
+          username = 'user_name'
+          password = 'your_password_here'
     
-    /END
+    /END // (only optional)
 `);
 
 console.log(config);
@@ -278,60 +282,41 @@ console.log(config);
 // JS object
 {
     App: {
-        name: "Nested Example",
-        version: "1.0.0",
-        debug: false,
-        Database: {
-            host: "db.example.com",
-            port: 3306,
-            user: "appuser",
-            password: "dbpassword",
-            Pool: {
-                min: 2,
-                max: 10,
-                idleTimeout: 300
-            }
-        },
-        Logging: {
-            level: "info",
-            logToFile: true,
-            filePath: "./logs/app.log"
+        title: 'My App', 
+        items: 25, 
+        debug: true
+    },
+    Server: {
+        host: 'localhost',
+        port: 8080,
+        useTLS: false,
+        Login: { 
+            username: 'user_name', 
+            password: 'your_password_here'
         }
     }
 }
 ```
 
----
-
-## API
-
-Only the `YINI` class is exposed in the public API, with two static methods: `parse` and `parseFile`.
-
-### `YINI.parse(yiniContent: string, strictMode?: boolean, bailSensitivity: 'auto' | 0 | 1 | 2 = "auto", includeMetaData = false): object`
-
-Parses YINI code from a string.  
-
-**Params:**
-- `yiniContent`: The YINI configuration as a string.
-- `strictMode`: (optional, default `false`) Parse in strict mode.
-- `bailSensitivity`: (optional, default `"auto"`) Error tolerance level.
-  * If `bailSensitivity` is `"auto"` then bail sensitivity level will be set to 0 if in non-strict mode, if in strict mode then level 1 will be used automatically.
-- `includeMetaData`: If true then additional meta data will be returned along the object.
-
-**Bail sensitivity levels:**
-- 0 = 'Ignore-Errors' // Don't bail on errors, persist and try to recover.
-- 1 = 'Abort-on-Errors'
-- 2 = 'Abort-Even-on-Warnings'
-
-Returns a JavaScript object representing the parsed configuration (YINI content).
-
-### `YINI.parseFile(filePath: string, strictMode?: boolean, bailSensitivity: 'auto' | 0 | 1 | 2 = "auto", includeMetaData = false): object`
-
-Parses YINI code from a file.
-- `filePath`: Path to the `.yini` file.
-- Other parameters are the same as `parse(..)`.
-
-Returns a JavaScript object representing the parsed YINI configuration file.
+### Output in JSON:
+```json
+{
+    "App": {
+        "title": "My App",
+        "items": 25,
+        "debug": true
+    },
+    "Server": {
+        "host": "localhost",
+        "port": 8080,
+        "useTLS": false,
+        "Login": {
+            "username": "user_name",
+            "password": "your_password_here"
+        }
+    }
+}
+```
 
 ---
 

package/dist/YINI.d.ts

@@ -1,43 +1,66 @@
-import { TJSObject } from './core/types';
+import { IAllUserOptions, TJSObject, TPreferredFailLevel } from './core/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.
  */
 export default class YINI {
-    static filePath: string;
+    private static g_tabSize;
     /**
-     * Parse YINI content into a JavaScript object.
+     * @returns The number of spaces per tab character used in error messages.
+     */
+    static getTabSize(): number;
+    /**
+     * Overrides the number of spaces per tab character used in error messages.
+     * Allowed range: 1-32.
+     */
+    static setTabSize(spaces: number): void;
+    /**
+     * Parse inline YINI content into a JavaScript object.
      *
      * @param yiniContent      YINI code as a string (multi‑line content supported).
      * @param strictMode       If `true`, enforce strict parsing rules (e.g. require `/END`, disallow trailing commas).
-     * @param bailSensitivity  Controls how errors and warnings are handled:
-     *   - `'auto'`               : Auto‑select level (strict→1, lenient→0)
+     * @param failLevel        Preferred bail sensitivity level, controls how errors and warnings are handled:
+     *   - `'auto'` (default)       : Auto‑select level (strict→1, lenient→0)
      *   - `0` / `'Ignore-Errors'`    : Continue parsing despite errors; log them and attempt recovery.
      *   - `1` / `'Abort-on-Errors'`  : Stop parsing on the first error.
      *   - `2` / `'Abort-Even-on-Warnings'`: Stop parsing on the first warning **or** error.
      * @param includeMetaData  If `true`, return additional metadata (e.g. warnings, statistics) alongside the parsed object.
      *
-     * @note The order of properties in each output object may differ from their order in the YINI source.
+     * @returns A JavaScript object representing the parsed YINI content.
+     */
+    static parse(yiniContent: string, strictMode?: boolean, failLevel?: TPreferredFailLevel, includeMetaData?: boolean): TJSObject;
+    /**
+     * Parse inline YINI content into a JavaScript object, using an options object for configuration.
+     *
+     * @param yiniContent      YINI code as a string (multi‑line content supported).
+     * @param options Optional settings to customize parsing and/or results, useful if you need more control.
      *
      * @returns A JavaScript object representing the parsed YINI content.
      */
-    static parse: (yiniContent: string, strictMode?: boolean, bailSensitivity?: "auto" | 0 | 1 | 2, includeMetaData?: boolean) => TJSObject;
+    static parse(yiniContent: string, options?: IAllUserOptions): TJSObject;
     /**
      * Parse a YINI file into a JavaScript object.
      *
      * @param yiniFile Path to the YINI file.
      * @param strictMode       If `true`, enforce strict parsing rules (e.g. require `/END`, disallow trailing commas).
-     * @param bailSensitivity  Controls how errors and warnings are handled:
-     *   - `'auto'`               : Auto‑select level (strict→1, lenient→0)
+     * @param failLevel        Preferred bail sensitivity level, controls how errors and warnings are handled:
+     *   - `'auto'` (default)       : Auto‑select level (strict→1, lenient→0)
      *   - `0` / `'Ignore-Errors'`    : Continue parsing despite errors; log them and attempt recovery.
      *   - `1` / `'Abort-on-Errors'`  : Stop parsing on the first error.
      *   - `2` / `'Abort-Even-on-Warnings'`: Stop parsing on the first warning **or** error.
      * @param includeMetaData  If `true`, return additional metadata (e.g. warnings, statistics) alongside the parsed object.
      *
-     * @note The order of properties in each output object may differ from their order in the YINI source.
+     * @returns A JavaScript object representing the parsed YINI content.
+     */
+    static parseFile(filePath: string, strictMode?: boolean, failLevel?: TPreferredFailLevel, includeMetaData?: boolean): TJSObject;
+    /**
+     * Parse a YINI file into a JavaScript object, using an options object for configuration.
+     *
+     * @param yiniFile Path to the YINI file.
+     * @param options Optional settings to customize parsing and/or results, useful if you need more control.
      *
      * @returns A JavaScript object representing the parsed YINI content.
      */
-    static parseFile: (filePath: string, strictMode?: boolean, bailSensitivity?: "auto" | 0 | 1 | 2, includeMetaData?: boolean) => TJSObject;
+    static parseFile(filePath: string, options?: IAllUserOptions): TJSObject;
 }

package/dist/YINI.js

@@ -2,113 +2,226 @@
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
-var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = __importDefault(require("fs"));
+const perf_hooks_1 = require("perf_hooks");
 const env_1 = require("./config/env");
+const ErrorDataHandler_1 = require("./core/ErrorDataHandler");
 const parseEntry_1 = require("./parseEntry");
 const pathAndFileName_1 = require("./utils/pathAndFileName");
 const print_1 = require("./utils/print");
+const string_1 = require("./utils/string");
+const DEFAULT_TAB_SIZE = 4; // De facto "modern default" (even though traditionally/historically it's 8).
+let _runtimeInfo = {
+    sourceType: 'Inline',
+    fileName: undefined,
+    fileByteSize: null,
+    lineCount: null,
+    timeIoMs: null,
+    preferredBailSensitivity: null,
+    sha256: null,
+};
+// Type guard: did the caller use the options-object form?
+const isOptionsObjectForm = (v) => {
+    return (v != null &&
+        typeof v === 'object' &&
+        // Note: If one wants, this can be relax to "typeof v === 'object'"
+        // but this keeps accidental booleans/strings out.
+        ('strictMode' in v ||
+            'failLevel' in v ||
+            'includeMetaData' in v ||
+            'includeDiagnostics' in v ||
+            'includeTiming' in v ||
+            'preserveUndefinedInMeta' in v ||
+            'requireDocTerminator' in v));
+};
+// Initial default values.
+const DEFAULT_OPTS = {
+    strictMode: false,
+    failLevel: 'auto',
+    includeMetaData: false,
+    includeDiagnostics: false,
+    includeTiming: false,
+    preserveUndefinedInMeta: false,
+    requireDocTerminator: false,
+};
 /**
  * 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.
  */
 class YINI {
-}
-_a = YINI;
-YINI.filePath = ''; // Used in error reporting.
-/**
- * Parse YINI content into a JavaScript object.
- *
- * @param yiniContent      YINI code as a string (multi‑line content supported).
- * @param strictMode       If `true`, enforce strict parsing rules (e.g. require `/END`, disallow trailing commas).
- * @param bailSensitivity  Controls how errors and warnings are handled:
- *   - `'auto'`               : Auto‑select level (strict→1, lenient→0)
- *   - `0` / `'Ignore-Errors'`    : Continue parsing despite errors; log them and attempt recovery.
- *   - `1` / `'Abort-on-Errors'`  : Stop parsing on the first error.
- *   - `2` / `'Abort-Even-on-Warnings'`: Stop parsing on the first warning **or** error.
- * @param includeMetaData  If `true`, return additional metadata (e.g. warnings, statistics) alongside the parsed object.
- *
- * @note The order of properties in each output object may differ from their order in the YINI source.
- *
- * @returns A JavaScript object representing the parsed YINI content.
- */
-YINI.parse = (yiniContent, strictMode = false, bailSensitivity = 'auto', includeMetaData = false) => {
-    (0, print_1.debugPrint)('-> Entered static parse(..) in class YINI\n');
-    // Important: First, before anything, trim beginning and trailing whitespaces!
-    yiniContent = yiniContent.trim();
-    if (!yiniContent) {
-        throw new Error('Syntax-Error: Unexpected blank YINI input');
+    /**
+     * @returns The number of spaces per tab character used in error messages.
+     */
+    static getTabSize() {
+        return this.g_tabSize;
     }
-    if (!yiniContent.endsWith('\n')) {
-        yiniContent += '\n';
+    /**
+     * Overrides the number of spaces per tab character used in error messages.
+     * Allowed range: 1-32.
+     */
+    static setTabSize(spaces) {
+        if (spaces < 1 || spaces > 32) {
+            new ErrorDataHandler_1.ErrorDataHandler('None/Ignore').pushOrBail(null, 'Fatal-Error', `Invalid tab size ${spaces} is out of range.`, 'Tab size must be between 1 and 32 spaces.');
+        }
+        this.g_tabSize = spaces;
     }
-    let level = 0;
-    if (bailSensitivity === 'auto') {
-        if (!strictMode)
-            level = 0;
-        if (strictMode)
-            level = 1;
+    // --- 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.
+    static parse(yiniContent, arg2, // strictMode | options
+    failLevel = DEFAULT_OPTS.failLevel, includeMetaData = DEFAULT_OPTS.includeMetaData) {
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        (0, print_1.debugPrint)('-> Entered static parse(..) in class YINI\n');
+        // Runtime guard to catch illegal/ambiguous calls coming from JS or any-cast code
+        if (isOptionsObjectForm(arg2) &&
+            (failLevel !== 'auto' || includeMetaData !== false)) {
+            throw new TypeError('Invalid call: when providing an options object, do not also pass positional parameters.');
+        }
+        // Normalize to a fully-required options object.
+        let userOpts;
+        // Required, makes all properties in T required, no undefined.
+        // const userOpts: Required<IAllUserOptions> = isOptionsObjectForm(arg2)
+        if (isOptionsObjectForm(arg2)) {
+            // Options-object Form.
+            /* parse = (
+                  yiniContent: string,
+                  options: IAllUserOptions,
+               )
+            */
+            userOpts = Object.assign(Object.assign({}, DEFAULT_OPTS), { strictMode: (_a = arg2.strictMode) !== null && _a !== void 0 ? _a : DEFAULT_OPTS.strictMode, failLevel: (_b = arg2.failLevel) !== null && _b !== void 0 ? _b : DEFAULT_OPTS.failLevel, includeMetaData: (_c = arg2.includeMetaData) !== null && _c !== void 0 ? _c : DEFAULT_OPTS.includeMetaData, includeDiagnostics: (_d = arg2.includeDiagnostics) !== null && _d !== void 0 ? _d : DEFAULT_OPTS.includeDiagnostics, includeTiming: (_e = arg2.includeTiming) !== null && _e !== void 0 ? _e : DEFAULT_OPTS.includeTiming, preserveUndefinedInMeta: (_f = arg2.preserveUndefinedInMeta) !== null && _f !== void 0 ? _f : DEFAULT_OPTS.preserveUndefinedInMeta, requireDocTerminator: (_g = arg2.requireDocTerminator) !== null && _g !== void 0 ? _g : DEFAULT_OPTS.requireDocTerminator });
+        }
+        else {
+            // Positional form.
+            /* parse = (
+                  yiniContent: string,
+                  strictMode?: boolean,
+                  failLevel?: TPreferredFailLevel,
+                  includeMetaData?: boolean,
+               )
+            */
+            userOpts = Object.assign(Object.assign({}, DEFAULT_OPTS), { strictMode: (_h = arg2) !== null && _h !== void 0 ? _h : DEFAULT_OPTS.strictMode, failLevel,
+                includeMetaData });
+        }
+        if (userOpts.includeMetaData && _runtimeInfo.sourceType === 'Inline') {
+            const lineCount = yiniContent.split(/\r?\n/).length; // Counts the lines.
+            const sha256 = (0, string_1.computeSha256)(yiniContent); // NOTE: Compute BEFORE any possible tampering of content.
+            _runtimeInfo.lineCount = lineCount;
+            _runtimeInfo.preferredBailSensitivity = userOpts.failLevel;
+            _runtimeInfo.sha256 = sha256;
+        }
+        // NOTE: Important: Do not trim or mutate the yiniContent here, due
+        // to it will mess up the line numbers in error reporting.
+        if (!yiniContent) {
+            throw new Error('Syntax-Error: Unexpected blank YINI input');
+        }
+        if (!yiniContent.endsWith('\n')) {
+            yiniContent += '\n';
+        }
+        let level = 0;
+        if (userOpts.failLevel === 'auto') {
+            if (!userOpts.strictMode)
+                level = 0;
+            if (userOpts.strictMode)
+                level = 1;
+        }
+        else {
+            level = userOpts.failLevel;
+        }
+        const coreOpts = {
+            isStrict: userOpts.strictMode,
+            bailSensitivity: level,
+            isIncludeMeta: userOpts.includeMetaData,
+            isWithDiagnostics: (0, env_1.isDev)() || (0, env_1.isDebug)() || userOpts.includeDiagnostics,
+            isWithTiming: (0, env_1.isDev)() || (0, env_1.isDebug)() || userOpts.includeTiming,
+            isKeepUndefinedInMeta: (0, env_1.isDebug)() || userOpts.preserveUndefinedInMeta,
+            isRequireDocTerminator: userOpts.requireDocTerminator,
+        };
+        (0, print_1.debugPrint)();
+        (0, print_1.debugPrint)('==== Call parse ==========================');
+        const result = (0, parseEntry_1._parseMain)(yiniContent, coreOpts, _runtimeInfo);
+        (0, print_1.debugPrint)('==== End call parse ==========================\n');
+        if ((0, env_1.isDev)()) {
+            console.log();
+            (0, print_1.devPrint)('YINI.parse(..): result:');
+            console.log(result);
+            (0, print_1.devPrint)('Complete result:');
+            (0, print_1.printObject)(result);
+        }
+        return result;
     }
-    else {
-        level = bailSensitivity;
+    // --- 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.
+    static parseFile(filePath, arg2, // strictMode | options
+    failLevel = DEFAULT_OPTS.failLevel, includeMetaData = DEFAULT_OPTS.includeMetaData) {
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        (0, print_1.debugPrint)('-> Entered static parseFile(..) in class YINI\n');
+        (0, print_1.debugPrint)('Current directory = ' + process.cwd());
+        // Runtime guard to catch illegal/ambiguous calls coming from JS or any-cast code
+        if (isOptionsObjectForm(arg2) &&
+            (failLevel !== 'auto' || includeMetaData !== false)) {
+            throw new TypeError('Invalid call: when providing an options object, do not also pass positional parameters.');
+        }
+        // Normalize to a fully-required options object.
+        let userOpts;
+        // Required, makes all properties in T required, no undefined.
+        // const userOpts: Required<IAllUserOptions> = isOptionsObjectForm(arg2)
+        if (isOptionsObjectForm(arg2)) {
+            // Options-object Form.
+            /* parse = (
+                  yiniContent: string,
+                  options: IAllUserOptions,
+               )
+            */
+            userOpts = Object.assign(Object.assign({}, DEFAULT_OPTS), { strictMode: (_a = arg2.strictMode) !== null && _a !== void 0 ? _a : DEFAULT_OPTS.strictMode, failLevel: (_b = arg2.failLevel) !== null && _b !== void 0 ? _b : DEFAULT_OPTS.failLevel, includeMetaData: (_c = arg2.includeMetaData) !== null && _c !== void 0 ? _c : DEFAULT_OPTS.includeMetaData, includeDiagnostics: (_d = arg2.includeDiagnostics) !== null && _d !== void 0 ? _d : DEFAULT_OPTS.includeDiagnostics, includeTiming: (_e = arg2.includeTiming) !== null && _e !== void 0 ? _e : DEFAULT_OPTS.includeTiming, preserveUndefinedInMeta: (_f = arg2.preserveUndefinedInMeta) !== null && _f !== void 0 ? _f : DEFAULT_OPTS.preserveUndefinedInMeta, requireDocTerminator: (_g = arg2.requireDocTerminator) !== null && _g !== void 0 ? _g : DEFAULT_OPTS.requireDocTerminator });
+        }
+        else {
+            // Positional form.
+            /* parse = (
+                  yiniContent: string,
+                  strictMode?: boolean,
+                  failLevel?: TPreferredFailLevel,
+                  includeMetaData?: boolean,
+               )
+            */
+            userOpts = Object.assign(Object.assign({}, DEFAULT_OPTS), { strictMode: (_h = arg2) !== null && _h !== void 0 ? _h : DEFAULT_OPTS.strictMode, failLevel,
+                includeMetaData });
+        }
+        if ((0, pathAndFileName_1.getFileNameExtension)(filePath).toLowerCase() !== '.yini') {
+            console.error('Invalid file extension for YINI file:');
+            console.error(`"${filePath}"`);
+            console.log('File does not have a valid ".yini" extension (case-insensitive).');
+            throw new Error('Error: Unexpected file extension for YINI file');
+        }
+        // ---- Phase 0: I/O ----
+        const timeStartMs = perf_hooks_1.performance.now();
+        // let content = fs.readFileSync(filePath, 'utf8')
+        const rawBuffer = fs_1.default.readFileSync(filePath); // Raw buffer for size.
+        const fileByteSize = rawBuffer.byteLength; // Byte size in UTF-8.
+        let content = rawBuffer.toString('utf8');
+        const timeEndMs = perf_hooks_1.performance.now();
+        _runtimeInfo.sourceType = 'File';
+        _runtimeInfo.fileName = filePath;
+        if (userOpts.includeMetaData) {
+            _runtimeInfo.lineCount = content.split(/\r?\n/).length; // Counts the lines.
+            _runtimeInfo.fileByteSize = fileByteSize;
+            _runtimeInfo.timeIoMs = +(timeEndMs - timeStartMs);
+            _runtimeInfo.preferredBailSensitivity = userOpts.failLevel;
+            _runtimeInfo.sha256 = (0, string_1.computeSha256)(content); // NOTE: Compute BEFORE any possible tampering of content.
+        }
+        let hasNoNewlineAtEOF = false;
+        if (!content.endsWith('\n')) {
+            content += '\n';
+            hasNoNewlineAtEOF = true;
+        }
+        const result = this.parse(content, userOpts.strictMode, userOpts.failLevel, userOpts.includeMetaData);
+        if (hasNoNewlineAtEOF) {
+            console.warn(`No newline at end of file, it's recommended to end a file with a newline. File:\n"${filePath}"`);
+        }
+        return result;
     }
-    const options = {
-        isStrict: strictMode,
-        bailSensitivityLevel: level,
-        isIncludeMeta: includeMetaData,
-        isWithDiagnostics: (0, env_1.isDev)() || (0, env_1.isDebug)(),
-        isWithTiming: (0, env_1.isDebug)(),
-    };
-    (0, print_1.debugPrint)();
-    (0, print_1.debugPrint)('==== Call parse ==========================');
-    const result = (0, parseEntry_1.parseMain)(yiniContent, options);
-    (0, print_1.debugPrint)('==== End call parse ==========================\n');
-    if ((0, env_1.isDev)()) {
-        console.log();
-        (0, print_1.devPrint)('YINI.parse(..): result:');
-        console.log(result);
-        (0, print_1.devPrint)('Complete result:');
-        (0, print_1.printObject)(result);
-    }
-    return result;
-};
-/**
- * Parse a YINI file into a JavaScript object.
- *
- * @param yiniFile Path to the YINI file.
- * @param strictMode       If `true`, enforce strict parsing rules (e.g. require `/END`, disallow trailing commas).
- * @param bailSensitivity  Controls how errors and warnings are handled:
- *   - `'auto'`               : Auto‑select level (strict→1, lenient→0)
- *   - `0` / `'Ignore-Errors'`    : Continue parsing despite errors; log them and attempt recovery.
- *   - `1` / `'Abort-on-Errors'`  : Stop parsing on the first error.
- *   - `2` / `'Abort-Even-on-Warnings'`: Stop parsing on the first warning **or** error.
- * @param includeMetaData  If `true`, return additional metadata (e.g. warnings, statistics) alongside the parsed object.
- *
- * @note The order of properties in each output object may differ from their order in the YINI source.
- *
- * @returns A JavaScript object representing the parsed YINI content.
- */
-YINI.parseFile = (filePath, strictMode = false, bailSensitivity = 'auto', includeMetaData = false) => {
-    (0, print_1.debugPrint)('Current directory = ' + process.cwd());
-    if ((0, pathAndFileName_1.getFileNameExtension)(filePath).toLowerCase() !== '.yini') {
-        console.error('Invalid file extension for YINI file:');
-        console.error(`"${filePath}"`);
-        console.log('File does not have a valid ".yini" extension (case-insensitive).');
-        throw new Error('Error: Unexpected file extension for YINI file');
-    }
-    let content = fs_1.default.readFileSync(filePath, 'utf8');
-    let hasNoNewlineAtEOF = false;
-    if (!content.endsWith('\n')) {
-        content += '\n';
-        hasNoNewlineAtEOF = true;
-    }
-    _a.filePath = filePath;
-    const result = _a.parse(content, strictMode, bailSensitivity, includeMetaData);
-    if (hasNoNewlineAtEOF) {
-        console.warn(`No newline at end of file, it's recommended to end a file with a newline. File:\n"${filePath}"`);
-    }
-    return result;
-};
+}
+YINI.g_tabSize = DEFAULT_TAB_SIZE; // Global tab size used in error messages.
 exports.default = YINI;