yini-parser 1.4.3 → 1.6.0

package/dist/core/errorDataHandler.d.ts

@@ -8,6 +8,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,7 +31,8 @@ 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;
@@ -50,6 +52,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

@@ -42,7 +42,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 +59,7 @@ class ErrorDataHandler {
         this.subjectType = subjectType;
         this.fileName = fileName;
         this.persistThreshold = bailSensitivityLevel;
+        this.isDiagnosticOutputEnabled = isDiagnosticOutputEnabled;
         this.isQuiet = isQuiet;
         this.isSilent = isSilent;
         this.isThrowOnError = isThrowOnError;
@@ -118,8 +120,8 @@ 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':
@@ -229,68 +231,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.d.ts

@@ -1,11 +1,15 @@
 import { ErrorDataHandler } from './errorDataHandler';
 import { IYiniAST } from './internalTypes';
 /**
- * Construct the final JavaScript Object.
- * Transforms the AST to the plain JS object.
+ * Construct the final JavaScript object.
+ * Transforms the AST into a plain JS object.
  *
- * - Keys are used exactly as-is.
- * - Order of properties matches the AST traversal order.
+ * Behavior:
+ * - Explicit top-level sections are mounted directly on the result.
+ * - In lenient mode, orphan top-level members are also mounted directly
+ *   on the result.
+ * - Any collision between an orphan member name and a top-level section
+ *   name results in an error.
  *
  * @note All `tag` fields MUST be ignored.
  */

package/dist/core/objectBuilder.js

@@ -1,63 +1,71 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.astToObject = void 0;
+// src/core/objectBuilder.ts
 const env_1 = require("../config/env");
 const print_1 = require("../utils/print");
 /**
- * Construct the final JavaScript Object.
- * Transforms the AST to the plain JS object.
+ * Construct the final JavaScript object.
+ * Transforms the AST into a plain JS object.
  *
- * - Keys are used exactly as-is.
- * - Order of properties matches the AST traversal order.
+ * Behavior:
+ * - Explicit top-level sections are mounted directly on the result.
+ * - In lenient mode, orphan top-level members are also mounted directly
+ *   on the result.
+ * - Any collision between an orphan member name and a top-level section
+ *   name results in an error.
  *
  * @note All `tag` fields MUST be ignored.
  */
+// src/core/objectBuilder.ts
 const astToObject = (ast, errorHandler) => {
     (0, print_1.debugPrint)('-> constructFinalObject(..)');
-    // return sectionChildrenToObject(ast.root)
     const out = {};
+    // 1) In lenient mode, mount orphan root members directly onto result.
+    if (!ast.isStrict) {
+        for (const [key, val] of ast.root.members) {
+            define(out, key, literalToJS(val));
+        }
+    }
+    // 2) Mount explicit top-level sections directly onto result.
     for (const child of ast.root.children) {
-        define(out, child.sectionName, sectionToObject(child));
+        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, errorHandler));
     }
     return out;
 };
 exports.astToObject = astToObject;
-/** Convert only the children of a section into an object keyed by sectionName. */
-// function sectionChildrenToObject(
-//     section: YiniSection,
-// ): Record<string, unknown> {
-//     const out: Record<string, unknown> = {}
-//     for (const child of section.children) {
-//         out[child.sectionName] = sectionToObject(child)
-//     }
-//     return out
-// }
-/** Convert a section (its members + nested sections) to a plain object. */
-// function sectionToObject(node: YiniSection): Record<string, unknown> {
+/**
+ * Convert a section (members + nested sections) to a plain object,
+ * preserving insertion order.
+ */
+// const sectionToObject = (node: IYiniSection): Record<string, unknown> => {
 //     const obj: Record<string, unknown> = {}
-//     // Members → properties
-//     for (const [key, val] of node.members.entries()) {
-//         obj[key] = literalToJS(val)
+//     // 1) Members (Map preserves insertion order).
+//     for (const [key, val] of node.members) {
+//         define(obj, key, literalToJS(val))
 //     }
-//     // Nested sections → nested objects keyed by sectionName
+//     // 2) Nested sections (array order preserved).
 //     for (const child of node.children) {
-//         obj[child.sectionName] = sectionToObject(child)
+//         define(obj, child.sectionName, sectionToObject(child))
 //     }
 //     return obj
 // }
-/**
- * Convert a section (members + nested sections) to a plain
- * object, preserving order.
- */
-const sectionToObject = (node) => {
+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;
 };
@@ -72,12 +80,6 @@ const sectionToObject = (node) => {
 const literalToJS = (v) => {
     const IS_LOCAL_DEBUG = false;
     (0, print_1.debugPrint)('In literalToJS(..)');
-    // if (!v) {
-    //     // NOTE: Only in lenient-mode, if parsing a
-    //     // member (key = value), but the value is invalid
-    //     // key will get undefined
-    //     return undefined
-    // }
     switch (v.type) {
         case 'String':
         case 'Number':
@@ -96,37 +98,20 @@ const literalToJS = (v) => {
             }
             const out = v.elems.map((elem) => {
                 const ret = literalToJS(elem);
-                if (IS_LOCAL_DEBUG) {
-                    if ((0, env_1.isDebug)()) {
-                        console.log(`elem:`);
-                        (0, print_1.printObject)(elem);
-                    }
+                if (IS_LOCAL_DEBUG && (0, env_1.isDebug)()) {
+                    console.log('elem:');
+                    (0, print_1.printObject)(elem);
                 }
                 return ret;
             });
-            if (IS_LOCAL_DEBUG) {
-                if ((0, env_1.isDebug)()) {
-                    console.log('Returning:');
-                    (0, print_1.printObject)(out);
-                }
+            if (IS_LOCAL_DEBUG && (0, env_1.isDebug)()) {
+                console.log('Returning:');
+                (0, print_1.printObject)(out);
             }
             return out;
         }
         case 'Object': {
             const out = {};
-            // for (const key of Object.keys(v.entries)) {
-            //     const entry = v.entries[key]
-            //     if (isScalar(entry)) {
-            //         // Scalar entries in object-literals: value
-            //         // out[key] = { type: entry.type, value: entry.value }
-            //         out[key] = entry.value
-            //     } else if (entry.type === 'List') {
-            //         out[key] = entry.elems.map(literalToJS)
-            //     } else {
-            //         out[key] = literalToJS(entry) // nested object-literal
-            //     }
-            // }
-            // Object.keys preserves property insertion order for plain objects
             for (const k of Object.keys(v.entries)) {
                 define(out, k, literalToJS(v.entries[k]));
             }
@@ -135,8 +120,8 @@ const literalToJS = (v) => {
     }
 };
 /**
- * Helper function, defines a property to preserve explicit insertion
- * order and enumerability.
+ * Helper function that defines a property while preserving explicit
+ * insertion order and enumerability.
  */
 const define = (obj, key, value) => {
     Object.defineProperty(obj, key, {

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,11 +14,16 @@ 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.
 };
+/**
+ * @note If editing any of these, the values in src/core/parsingRules/modeFromRulesMatcher.ts
+ * must match too.
+ */
 const DEFAULT_LENIENT_OPTS = {
     ...BASE_DEFAULTS,
     strictMode: false,
@@ -28,13 +33,17 @@ const DEFAULT_LENIENT_OPTS = {
     requireDocTerminator: 'optional',
     treatEmptyValueAsNull: 'allow',
 };
+/**
+ * @note If editing any of these, the values in src/core/parsingRules/modeFromRulesMatcher.ts
+ * must match too.
+ */
 const DEFAULT_STRICT_OPTS = {
     ...BASE_DEFAULTS,
     strictMode: true,
     failLevel: 'errors',
     // Below are options for pure rules:
     onDuplicateKey: 'error',
-    requireDocTerminator: 'optional',
+    requireDocTerminator: 'required',
     treatEmptyValueAsNull: 'disallow',
 };
 //# sourceMappingURL=defaultParserOptions.js.map

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,
@@ -32,8 +35,6 @@ exports.toCoreOptions = toCoreOptions;
 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 ||
@@ -43,9 +44,10 @@ const isOptionsObjectForm = (v) => {
             'onDuplicateKey' in v ||
             'requireDocTerminator' in v ||
             'treatEmptyValueAsNull' in v ||
+            'logDiagnostics' in v ||
             'quiet' in v ||
             'silent' in v ||
-            'isThrowOnError' in v));
+            'throwOnError' in v));
 };
 exports.isOptionsObjectForm = isOptionsObjectForm;
 const inferModeFromArgs = (arg2) => {

package/dist/core/parsingRules/modeFromRulesMatcher.d.ts

@@ -1,4 +1,4 @@
-import { ParseOptions } from 'querystring';
+import { ParseOptions } from '../../types';
 import { IParseCoreOptions, TExactMode } from '../internalTypes';
 export declare const matchModeFromParseOptions: (parserOptions: ParseOptions) => TExactMode;
 /**

package/dist/core/parsingRules/modeFromRulesMatcher.js

@@ -1,14 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.matchModeFromCoreOptions = exports.matchModeFromParseOptions = void 0;
+// src/core/parsingRules/modeFromRulesMatcher.ts
+// import { ParseOptions } from 'querystring'
 const env_1 = require("../../config/env");
 const print_1 = require("../../utils/print");
 const errorDataHandler_1 = require("../errorDataHandler");
 const optionsFunctions_1 = require("../options/optionsFunctions");
+/*
+ * Strict-mode defaults are:
+ * - onDuplicateKey:        'error' →       2
+ * - requireDocTerminator:  'required' →    2
+ * - treatEmptyValueAsNull: 'disallow' →    2
+ */
 const MODE_PROFILES = {
     lenient: [0, 0, 0],
     //   moderate: [1, 0, 1],
-    strict: [2, 0, 2],
+    strict: [2, 2, 2],
     //'pedantic'
     //'paranoid'
 };
@@ -22,7 +30,7 @@ const matchModeFromCoreOptions = (coreOptions) => {
     (0, print_1.debugPrint)('-> matchModeFromRules(..):');
     if (!coreOptions?.rules) {
         // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-        new errorDataHandler_1.ErrorDataHandler('None/Ignore').pushOrBail(undefined, 'Fatal-Error', `The passed input object is missing rules object.`, 'Option might be of wrong type, it must be core options.');
+        new errorDataHandler_1.ErrorDataHandler('None/Ignore').pushOrBail(undefined, 'Fatal-Error', `The passed input object is missing rules object.`, 'The passed option object may be of the wrong type; expected core options.');
     }
     // debugPrint(
     //     'coreOptions.rules.?onDuplicateKey        = ' +
@@ -60,11 +68,12 @@ const inferTParserModeExact = (rules) => {
     // debugPrint('rules.onDuplicateKey        = ' + rules.onDuplicateKey)
     // debugPrint('rules.requireDocTerminator  = ' + rules.requireDocTerminator)
     // debugPrint('rules.treatEmptyValueAsNull = ' + rules.treatEmptyValueAsNull)
-    // Note, **each rule** is scored on a strictness scale (0 = lenient, 1 = medium, 2 = strict).
+    // Each rule is scored on a strictness scale:
+    // 0 = lenient / permissive, 1 = warning-level / intermediate, 2 = strict / enforcing.
     const vector = [
-        scoreDupl(rules.onDuplicateKey),
-        scoreTerm(rules.requireDocTerminator),
-        scoreEmpty(rules.treatEmptyValueAsNull),
+        scoreDuplicateKey(rules.onDuplicateKey),
+        scoreRequireDocTerminator(rules.requireDocTerminator),
+        scoreEmptyValue(rules.treatEmptyValueAsNull),
     ];
     (0, print_1.debugPrint)('** vector:');
     // isDebug() && printObject(vector)
@@ -76,29 +85,29 @@ const inferTParserModeExact = (rules) => {
     }
     return { mode: 'custom', vector };
 };
-const scoreDupl = (v) => {
+const scoreDuplicateKey = (v) => {
     switch (v) {
         case 'keep-first':
         case 'warn-and-keep-first':
-            return 0; // Rule in lenient mode.
+            return 0; // Lenient / permissive rule level.
         case 'overwrite':
         case 'warn-and-overwrite':
             return 1;
         case 'error':
-            return 2; // Rule in strict mode.
+            return 2; // Strict / enforcing rule level.
     }
 };
-const scoreTerm = (v) => {
+const scoreRequireDocTerminator = (v) => {
     switch (v) {
         case 'optional':
-            return 0; // Rule in lenient and strict mode.
+            return 0; // Lenient / permissive rule level.
         case 'warn-if-missing':
             return 1;
         case 'required':
-            return 2;
+            return 2; // Strict / enforcing rule level.
     }
 };
-const scoreEmpty = (v) => {
+const scoreEmptyValue = (v) => {
     switch (v) {
         case 'allow':
             return 0; // Rule in lenient mode.