yini-parser 1.1.0-beta → 1.3.0-beta

package/CHANGELOG.md

@@ -1,6 +1,54 @@
 # CHANGELOG
 
-## --dev/uppcoming--
+## 1.3.0-beta - 2025 Sep
+- **Fixed:** bug where `buildResultMetadata(..)` could occasionally produce an `undefined` error.
+- **Renamed:** some public (user facing) interfaces to be more ergonomic for end users:
+  * `AllUserOptions` to `ParseOptions`
+  * `PrimaryUserParams` to `BasicOptions`
+- **Renamed:** public (user facing) parsing rule type to be more ergonomic for end users:
+  * `OnDuplicateKey` to `DuplicateKeyPolicy`
+- **Clarified:** the `strictMode` parameter in TSDoc: it defines the baseline
+  ruleset (true = strict, false = lenient). It's only a starting
+  point—rule-specific options (e.g., `treatEmptyValueAsNull`, `onDuplicateKey`)
+  may override parts of that ruleset. When overrides are provided, the
+   effective mode becomes custom.
+- **New:** Added user facing parsing rule value types `DocumentTerminatorRule` and `EmptyValueRule`.
+- **New:** Added `quiet` option, prints only errors to the console and warnings/info/etc. are not printed. This does not affect diagnostics captured in metadata.
+- **New:** Added `silent` option, no console output will be outputted at all, not even errors. Programmatic callers should rely on returned metadata, CLI users should rely on the exit code.
+- **(Heads-up) New:** Added `throwOnError` option, when `true` (default) the parser throws on parse errors, when `false` errors are reported via diagnostics without throwing.
+  - **Current default:** `true`.
+  - **Planned change:** Next release will switch the default to `false`.
+  - **Action:** Set throwOnError: true (to keep throwing) or `throwOnError: false` (to adopt the future behavior) explicitly.
+- **Updated:** Metadata now includes `effectiveMode` in `meta.diagnostics.effectiveOptions`, and the metadata version has been bumped to `1.1.1`.
+  The fields `strictMode` and `effectiveOptions` in `meta.diagnostics` now correctly reflect when any rules have been overridden from the initially selected mode.
+- **CI/Tooling (GitHub Actions):** Added security and quality checks:
+  - **Security:** CodeQL, dependency checke (`npm audit`) + lockfile-lint, Gitleaks (SARIF), Semgrep (SARIF).
+  - **Grammar drift check:** ANTLR-based verification to ensure generated sources are committed.
+  - **Regression tests:** run across a Node/OS matrix.
+  - **Releases:** npm publish with provenance (tag-driven).
+- **Updated** the logic and message(s) when parser summary is shown.
+
+## 1.2.0-beta - 2025 Sep
+- **Fixed:** `parseFile()` now correctly passes through all options (e.g. `includeDiagnostics`) so they work and matches as in `parse(..)`.
+- **Fixed:** typo (`in in`) in file parsing error message.
+- **Updated:** metadata structure bumped to version 1.1.0, and below added (among other things):
+    ```ts
+    preservesOrder: true // Member/section order: platform-, implementation-, and language-specific. Not mandated by the YINI spec.
+    orderGuarantee: 'implementation-defined'
+    orderNotes?: string
+    ```
+- **Refactored:** the static public (user-facing) YINI class to use per-invocation runtime state, preventing race conditions in runtime info when multiple calls to `parse(..)` / `parseFile(..)` run in parallel.
+- **Refactored file layout:** Moved and renamed files in `src/`
+  * File `src/parseEntry.ts` renamed and moved to `src/src/pipeline.ts`, 
+      - And in that file, rename the method/function `_parseEntry(..)` to `runPipeline(..)`.
+  * Renamed the file `core/types.ts` to `core/internalTypes.ts`
+      - And moved public (user-facing) types and interfaces into its own file `src/types/index.ts`.
+  * Moved the file `src/yiniHelpers.ts` to `src/utils/yiniHelpers.ts`.
+- **Renamed:** `includeMetaData` to `includeMetadata`.
+- **Updated:** Codebase now consistently uses the `ParsedObject` type,
+replacing the older `TJSObject` type for representing parsed YINI.
+- **Docs:** Expanded and improved TSDoc of several of the functions in the public API.
+- **Internal:** Unit tests are now colocated with their source code files in `src/**`. So there is 1:1 visibility between code and its unit tests, and less chance of missing coverage, etc.
 
 ## 1.1.0-beta - 2025 Sep
 ### Parser
@@ -15,7 +63,7 @@
   const config= YINI.parse(yini, {
             strictMode: false,
             failLevel: 'auto',
-            includeMetaData: false,
+            includeMetadata: false,
             requireDocTerminator: false,
         })  
   ```  

package/README.md

@@ -2,7 +2,7 @@
 
 A TypeScript/Node.js parser for YINI — A type-safe, structured, and human-readable config format with nested sections, types, comments, and support for strict validation.
 
-[![npm version](https://img.shields.io/npm/v/yini-parser.svg)](https://www.npmjs.com/package/yini-parser) [![All Tests](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)
+[![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)
 
 ```sh
 npm install yini-parser
@@ -17,7 +17,7 @@ YINI (Yet another INI): YINI is a configuration format designed for readability
 
 ➡️ See full [documentation or YINI format specification](https://github.com/YINI-lang/YINI-spec)
 
-⭐ **Enjoying YINI?** If you find this project useful, please consider [starring it on GitHub](https://github.com/YINI-lang/yini-parser-typescript) — it helps others discover it!
+⭐ **Enjoying YINI?** If you like this project, [star it on GitHub](https://github.com/YINI-lang/yini-parser-typescript) — it helps a lot, thank you!
 
 ---
 

package/dist/YINI.d.ts

@@ -1,4 +1,4 @@
-import { IAllUserOptions, TJSObject, TPreferredFailLevel } from './core/types';
+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.
@@ -18,49 +18,177 @@ export default class YINI {
     /**
      * 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 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.
-     *
-     * @returns A JavaScript object representing the parsed YINI content.
+     * @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 failLevel          Preferred bail sensitivity level, controls if and when parsing should stop on problems:
+     *   - `'auto'` (default)      : Auto‑select level (strict → `'errors'`, lenient → `'ignore-errors'`)
+     *   - `'ignore-errors'`       : Continue parsing despite errors; log them and attempt recovery.
+     *   - `'errors'`              : Stop parsing on the first error.
+     *   - `'warnings-and-errors'` : Stop parsing on the first warning **or** error.
+     * @param includeMetadata    If `true`, return additional metadata (e.g. warnings, statistics) alongside the parsed object.
+     *
+     * @returns {ParsedObject | YiniParseResult} The parsed YINI content.
+     *
+     * By default (`includeMetadata = false`), this method returns a plain JavaScript object:
+     *
+     * `
+     * export type ParsedObject = any
+     * `
+     *
+     * If `includeMetadata = true`, the return value is wrapped in a container that also
+     * includes parsing metadata:
+     *
+     * `
+     * export interface YiniParseResult {
+     *   result: ParsedObject
+     *   meta: ResultMetadata
+     * }
+     * `
      */
-    static parse(yiniContent: string, strictMode?: boolean, failLevel?: TPreferredFailLevel, includeMetaData?: boolean): TJSObject;
+    static parse(yiniContent: string, strictMode?: boolean, failLevel?: PreferredFailLevel, includeMetadata?: boolean): ParsedObject | YiniParseResult;
     /**
      * 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.
+     *        For all options, see types/ParseOptions.
+     *
+     * @param options.failLevel - Preferred bail sensitivity level, controls if and when parsing should stop on problems:
+     *   Accepts:
+     *     `'ignore-errors'` - Continue despite errors, persist and try to recover.
+     *     `'errors'` - Stop parsing on the first error.
+     *     `'warnings-and-errors'` - Stop parsing on the first warning or error.
+     *   (Type: TPreferredFailLevel; exact behavior is implementation-defined.)
+     * @param options.includeDiagnostics - Include diagnostics in the returned metadata.
+     *   Requires: `includeMetadata = true`. Ignored otherwise.
+     * @param options.includeMetadata - Attach a metadata object to the parse result
+     *   (e.g., timings, diagnostics).
+     * @param options.includeTiming - Include timing information for parser phases in metadata.
+     *   Requires: `includeMetadata = true`. Ignored otherwise.
+     * @param options.onDuplicateKey - Strategy/handler when encountering a duplicate key.
+     *   Allowed values: `'warn-and-keep-first'` | `'warn-and-overwrite'` | `'keep-first'` (silent, first wins) | `'overwrite'` (silent, last wins) | `'error'`.
+     * @param options.preserveUndefinedInMeta - Keep properties with value `undefined` inside
+     *   the returned metadata. Requires: `includeMetadata = true`. Ignored otherwise.
+     * @param options.quiet - Show only errors, will suppress warnings and messages sent to the console/log.
+     *   Does not affect warnings included in returned metadata.
+     * @param options.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.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.
+     *
+     * @returns {ParsedObject | YiniParseResult} The parsed YINI content.
+     *
+     * By default (`includeMetadata = false`), this method returns a plain JavaScript object:
+     *
+     * `
+     * export type ParsedObject = any
+     * `
+     *
+     * If `includeMetadata = true`, the return value is wrapped in a container that also
+     * includes parsing metadata:
      *
-     * @returns A JavaScript object representing the parsed YINI content.
+     * `
+     * export interface YiniParseResult {
+     *   result: ParsedObject
+     *   meta: ResultMetadata
+     * }
+     * `
      */
-    static parse(yiniContent: string, options?: IAllUserOptions): TJSObject;
+    static parse(yiniContent: string, options?: ParseOptions): ParsedObject | YiniParseResult;
     /**
      * 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 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.
-     *
-     * @returns A JavaScript object representing the parsed YINI content.
+     * @param yiniFile           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'`)
+     *   - `'ignore-errors'`       : Continue parsing despite errors; log them and attempt recovery.
+     *   - `'errors'`              : Stop parsing on the first error.
+     *   - `'warnings-and-errors'` : Stop parsing on the first warning **or** error.
+     * @param includeMetadata    If `true`, return additional metadata (e.g. warnings, statistics) alongside the parsed object.
+     *
+     * @returns {ParsedObject | YiniParseResult} The parsed YINI content.
+     *
+     * By default (`includeMetadata = false`), this method returns a plain JavaScript object:
+     *
+     * `
+     * export type ParsedObject = any
+     * `
+     *
+     * If `includeMetadata = true`, the return value is wrapped in a container that also
+     * includes parsing metadata:
+     *
+     * `
+     * export interface YiniParseResult {
+     *   result: ParsedObject
+     *   meta: ResultMetadata
+     * }
+     * `
      */
-    static parseFile(filePath: string, strictMode?: boolean, failLevel?: TPreferredFailLevel, includeMetaData?: boolean): TJSObject;
+    static parseFile(filePath: string, strictMode?: boolean, failLevel?: PreferredFailLevel, includeMetadata?: boolean): ParsedObject | YiniParseResult;
     /**
      * 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.
+     *        For all options, see types/ParseOptions.
+     *
+     * @param options.failLevel - Preferred bail sensitivity level, controls if and when parsing should stop on problems:
+     *   Accepts:
+     *     `'ignore-errors'` - Continue despite errors, persist and try to recover.
+     *     `'errors'` - Stop parsing on the first error.
+     *     `'warnings-and-errors'` - Stop parsing on the first warning or error.
+     *   (Type: TPreferredFailLevel; exact behavior is implementation-defined.)
+     * @param options.includeDiagnostics - Include diagnostics in the returned metadata.
+     *   Requires: `includeMetadata = true`. Ignored otherwise.
+     * @param options.includeMetadata - Attach a metadata object to the parse result
+     *   (e.g., timings, diagnostics).
+     * @param options.includeTiming - Include timing information for parser phases in metadata.
+     *   Requires: `includeMetadata = true`. Ignored otherwise.
+     * @param options.onDuplicateKey - Strategy/handler when encountering a duplicate key.
+     *   Allowed values: `'warn-and-keep-first'` | `'warn-and-overwrite'` | `'keep-first'` (silent, first wins) | `'overwrite'` (silent, last wins) | `'error'`.
+     * @param options.preserveUndefinedInMeta - Keep properties with value `undefined` inside
+     *   the returned metadata. Requires: `includeMetadata = true`. Ignored otherwise.
+     * @param options.quiet - Show only errors, will suppress warnings and messages sent to the console/log.
+     *   Does not affect warnings included in returned metadata.
+     * @param options.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.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.
+     *
+     * @returns {ParsedObject | YiniParseResult} The parsed YINI content.
+     *
+     * By default (`includeMetadata = false`), this method returns a plain JavaScript object:
+     *
+     * `
+     * export type ParsedObject = any
+     * `
+     *
+     * If `includeMetadata = true`, the return value is wrapped in a container that also
+     * includes parsing metadata:
      *
-     * @returns A JavaScript object representing the parsed YINI content.
+     * `
+     * export interface YiniParseResult {
+     *   result: ParsedObject
+     *   meta: ResultMetadata
+     * }
+     * `
      */
-    static parseFile(filePath: string, options?: IAllUserOptions): TJSObject;
+    static parseFile(filePath: string, options?: ParseOptions): ParsedObject | YiniParseResult;
 }