yini-cli 1.3.4 → 1.5.0

package/README.md

@@ -1,13 +1,12 @@
 # YINI CLI
-> **Readable configuration without indentation pitfalls or JSON verbosity.**  
 
-**The official CLI for validating, inspecting, and converting YINI configuration files to JSON or JavaScript, built by the YINI-lang project.**
+The official CLI for validating, inspecting, and converting YINI configuration files to JSON or JavaScript, maintained by the YINI-lang project.
 
-*YINI is an INI-inspired, human-friendly configuration format with real structure, nested sections, comments, and predictable parsing.*
+YINI is an INI-inspired, human-readable configuration format with explicit structure, nested sections, comments, and predictable parsing.
 
-[![npm version](https://img.shields.io/npm/v/yini-cli.svg)](https://www.npmjs.com/package/yini-cli) [![All Test Suites](https://github.com/YINI-lang/yini-cli/actions/workflows/run-all-tests.yml/badge.svg)](https://github.com/YINI-lang/yini-cli/actions/workflows/run-all-tests.yml) [![Regression Tests](https://github.com/YINI-lang/yini-cli/actions/workflows/run-regression-tests.yml/badge.svg)](https://github.com/YINI-lang/yini-cli/actions/workflows/run-regression-tests.yml) [![CLI Test CI](https://github.com/YINI-lang/yini-cli/actions/workflows/run-cli-test.yml/badge.svg)](https://github.com/YINI-lang/yini-cli/actions/workflows/run-cli-test.yml) [![npm downloads](https://img.shields.io/npm/dm/yini-cli)](https://www.npmjs.com/package/yini-cli)
+YINI is intended to emphasize clarity, readability, explicit structure, predictability, and deterministic parsing, while remaining simple, but not simplistic.
 
-Designed for developers and teams who want human-edited configuration with explicit structure and no indentation-based semantics.
+[![npm version](https://img.shields.io/npm/v/yini-cli.svg)](https://www.npmjs.com/package/yini-cli) [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![All Test Suites](https://github.com/YINI-lang/yini-cli/actions/workflows/run-all-tests.yml/badge.svg)](https://github.com/YINI-lang/yini-cli/actions/workflows/run-all-tests.yml) [![Regression Tests](https://github.com/YINI-lang/yini-cli/actions/workflows/run-regression-tests.yml/badge.svg)](https://github.com/YINI-lang/yini-cli/actions/workflows/run-regression-tests.yml) [![CLI Test CI](https://github.com/YINI-lang/yini-cli/actions/workflows/run-cli-test.yml/badge.svg)](https://github.com/YINI-lang/yini-cli/actions/workflows/run-cli-test.yml) 
 
 ## Quick Start
 
@@ -37,7 +36,7 @@ YINI CLI requires Node.js **v20 or later**.
 
 3. **Test functionality**  
     Create a simple test file, for example: `config.yini`:
-    ```yini
+    ```ini
     ^ App
     name = "My App Title"
     version = "1.2.3"
@@ -82,11 +81,11 @@ Source: [config.yini](./samples/config.yini)
 
 ---
 
-## 🙋‍♀️ Why YINI?
+## YINI characteristics
 - **Indentation-independent structure:** YINI is indentation-independent — whitespace never alters structural meaning.
-- **Explicit nesting:** It uses clear header markers (`^`, `^^`, `^^^`) to define hierarchy, making large configurations easier to scan and refactor.
+- **Explicit nesting:** Section markers such as `^`, `^^`, and `^^^` define hierarchy explicitly.
 - **Multiple data types:** Supports booleans (`true` / `false`, `yes` / `no`, etc.), numbers, lists, and inline objects, with explicit string syntax.
-- **Comment support:** YINI supports multiple comment styles (`#`, `//`, `/* ... */`, and `;`), making it easier to document configuration directly in the file.
+- **Comment support:** YINI supports multiple comment styles (`#`, `//`, `/* ... */`, and `;`) for documenting configuration directly in the file.
 - **Predictable parsing:** Well-defined rules with optional strict and lenient modes for different use cases.
 
 ---
@@ -128,10 +127,112 @@ yini parse --help
 
 ---
 
+## Why YINI?
+
+YINI is intended for configuration files where human readability, explicit structure, and predictable parsing are more important than minimal syntax or maximum flexibility.
+
+Compared with common configuration formats:
+- **INI:** YINI supports clearer nested sections and typed values.
+- **JSON:** YINI supports comments and is easier to edit by hand.
+- **YAML:** YINI does not use indentation to define structure.
+- **TOML:** YINI uses explicit section markers for hierarchy instead of dotted table names.
+
+The same small configuration can be written in several formats:
+
+### YINI
+```ini
+^ Application
+name = 'demo'
+environment = 'dev'
+
+^^ Server
+host = 'localhost'
+ports = [8080, 8081]
+
+^^^ TLS
+enabled = true
+mode = 'optional'
+```
+
+- `Application` contains the top-level application settings.
+- `Server` is nested under `Application`.
+- `TLS` is nested under `Server`.
+- The section markers `^` make the nesting explicit. Indentation is optional and not required for structure.
+- Strings can use either `'` or `"`.
+
+### JSON
+```json
+{
+  "Application": {
+    "name": "demo",
+    "environment": "dev",
+    "Server": {
+      "host": "localhost",
+      "ports": [8080, 8081],
+      "TLS": {
+        "enabled": true,
+        "mode": "optional"
+      }
+    }
+  }
+}
+```
+
+### YAML
+```yaml
+Application:
+  name: demo
+  environment: dev
+  Server:
+    host: localhost
+    ports:
+      - 8080
+      - 8081
+    TLS:
+      enabled: true
+      mode: optional
+```
+
+### TOML
+```toml
+[Application]
+name = "demo"
+environment = "dev"
+
+[Application.Server]
+host = "localhost"
+ports = [8080, 8081]
+
+[Application.Server.TLS]
+enabled = true
+mode = "optional"
+```
+
+YINI may not be the right choice when you need mature ecosystem support, existing schema tooling, or maximum compatibility with infrastructure that already expects JSON, YAML, or TOML. The format and parser are still alpha-stage and best suited for testing, experiments, and early integration feedback.
+
+---
+
+## Feedback and bug reports
+
+If you find a problem, please open an issue on GitHub:
+
+- [Report a bug or issue](https://github.com/YINI-lang/yini-cli/issues)
+
+When reporting parser behavior, it is helpful to include:
+- The YINI input that caused the issue.
+- The command and options used.
+- The expected result.
+- The actual result or error message.
+- The installed `yini-cli` version.
+- The Node.js version used.
+- The operating system and version used.
+
+---
+
 ## A closer look at YINI
 
 Here's a small example showing YINI structure and comments:
-```yini
+```ini
     // This is a comment in YINI
 
     ^ App                      // Defines section (group) "App" 
@@ -177,10 +278,8 @@ Here's a small example showing YINI structure and comments:
 }
 ```
 
-That's it!
-
-- ▶️ See more on [YINI Homepage](https://yini-lang.org/?utm_source=github&utm_medium=referral&utm_campaign=yini_cli&utm_content=readme_middle).
-- ▶️ Link to [Demo Apps](https://github.com/YINI-lang/yini-demo-apps/tree/main) with complete basic usage.
+- [YINI Homepage](https://yini-lang.org/?utm_source=github&utm_medium=referral&utm_campaign=yini_cli&utm_content=readme_middle).
+- [YINI Demo Apps](https://github.com/YINI-lang/yini-demo-apps/tree/main) with usage examples.
 
 ---
 
@@ -196,8 +295,8 @@ The `parse` command supports multiple output formats:
 | `yini parse config.yini --js`           | JavaScript object    | JavaScript-style object (unquoted keys, single quotes). |
 | `yini parse config.yini -o out.json`    | File output          | Writes formatted JSON to file (default format). |
 
->💡 `--js` and `--compact` are mutually exclusive.  
->💡 Tip: You can combine --output with any style flag to control both formatting and destination.
+> `--js` and `--compact` are mutually exclusive.  
+> `--output` can be combined with a style flag to control both formatting and destination.
 
 ### Output File Handling
 
@@ -237,20 +336,20 @@ Use `--overwrite` to force replacement.
 ---
 
 ## Contributing
-Contributions, bug reports, and feedback are welcome. Even small improvements or suggestions are appreciated.  
+Bug reports, feedback, and contributions are welcome.  
 
-If this tool is useful to you, a GitHub star helps more people discover the project and supports future development.
+GitHub Issues and Discussions are available for feedback and project discussion.
 
 ---
 
 ## License
-This project is licensed under the Apache-2.0 license — see the [LICENSE](./LICENSE) file for details.
-
-In this project on GitHub, the `libs` directory contains third party software and each is licensed under its own license which is described in its own license file under the respective directory under `libs`.
+This project is licensed under the Apache License 2.0 — see the [LICENSE](./LICENSE) file for details.
 
 ---
 
 **^YINI ≡**  
-> Readable like INI. Structured like JSON. No indentation surprises.  
+> YINI is a human-readable configuration format designed for clarity, readability, explicit structure, predictability, and deterministic parsing.
+> 
+> See the specification for syntax and format details.  
 
 [yini-lang.org](https://yini-lang.org/?utm_source=github&utm_medium=referral&utm_campaign=yini_cli&utm_content=readme_footer) · [YINI-lang on GitHub](https://github.com/YINI-lang)  

package/dist/commands/commonFunctions.d.ts

@@ -0,0 +1,15 @@
+import { IGlobalOptions } from '../types.js';
+export type TValidateRunMode = 'file' | 'directory';
+export declare const printStdout: (options: IGlobalOptions, text: string) => void;
+export declare const printStderr: (options: IGlobalOptions, text: string) => void;
+export declare const printWarning: (options: IGlobalOptions, text: string) => void;
+export declare const resolveStrictMode: (options: IGlobalOptions) => boolean;
+export declare const resolveRunModeFromTargets: (targets: string[]) => TValidateRunMode;
+export declare const getDisplayBaseDir: (targets: string[]) => string;
+export declare const toDisplayPath: (filePath: string, baseDir: string) => string;
+/**
+ *
+ * @note Windows safe, since Windows paths are case-insensitive,
+ * so on Windows cases are normalized too.
+ */
+export declare const assertInputAndOutputAreDifferent: (srcPath: string, destPath: string) => void;

package/dist/commands/commonFunctions.js

@@ -0,0 +1,76 @@
+// src/commands/commonFunctions.ts
+import fs from 'node:fs';
+import path from 'node:path';
+export const printStdout = (options, text) => {
+    if (options.silent)
+        return;
+    console.log(text);
+};
+export const printStderr = (options, text) => {
+    if (options.silent)
+        return;
+    console.error(text);
+};
+export const printWarning = (options, text) => {
+    if (options.silent)
+        return;
+    if (options.quiet)
+        return;
+    console.warn(text);
+};
+export const resolveStrictMode = (options) => {
+    if (options.strict && options.lenient) {
+        throw new Error('--strict and --lenient cannot be used together.');
+    }
+    if (options.strict)
+        return true;
+    if (options.lenient)
+        return false;
+    return false; // Default = lenient
+};
+export const resolveRunModeFromTargets = (targets) => {
+    for (const target of targets) {
+        const resolved = path.resolve(target);
+        if (!fs.existsSync(resolved)) {
+            throw new Error(`Path does not exist: "${target}"`);
+        }
+        if (fs.statSync(resolved).isDirectory()) {
+            return 'directory';
+        }
+    }
+    return 'file';
+};
+export const getDisplayBaseDir = (targets) => {
+    if (!targets.length) {
+        return process.cwd();
+    }
+    if (targets.length === 1) {
+        const resolved = path.resolve(targets[0]);
+        if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+            return resolved;
+        }
+        return path.dirname(resolved);
+    }
+    return process.cwd();
+};
+export const toDisplayPath = (filePath, baseDir) => {
+    const relative = path.relative(baseDir, filePath);
+    if (!relative || relative.startsWith('..')) {
+        return filePath;
+    }
+    return relative;
+};
+/**
+ *
+ * @note Windows safe, since Windows paths are case-insensitive,
+ * so on Windows cases are normalized too.
+ */
+export const assertInputAndOutputAreDifferent = (srcPath, destPath) => {
+    const resolvedSrc = path.resolve(srcPath);
+    const resolvedDest = path.resolve(destPath);
+    const normalizedSrc = process.platform === 'win32' ? resolvedSrc.toLowerCase() : resolvedSrc;
+    const normalizedDest = process.platform === 'win32' ? resolvedDest.toLowerCase() : resolvedDest;
+    if (normalizedSrc === normalizedDest) {
+        throw new Error('Output file must be different from the input file.');
+    }
+};

package/dist/commands/parseCommand.d.ts

@@ -21,5 +21,5 @@ export interface IParseCommandOptions extends IGlobalOptions {
  * @returns
  */
 export declare const shouldSkipBecauseDestNewer: (file: string, optionOverwrite?: boolean | undefined, outputFile?: string) => boolean;
-export declare const isAllowWriteOutput: (srcPath: string, destPath: string, newContent: string, overwrite?: boolean) => boolean;
+export declare const isAllowWriteOutput: (commandOptions: IParseCommandOptions, srcPath: string, destPath: string, newContent: string, overwrite?: boolean) => boolean;
 export declare const parseFile: (file: string, commandOptions: IParseCommandOptions) => void;

package/dist/commands/parseCommand.js

@@ -1,9 +1,10 @@
 // src/commands/parseCommand.ts
-import fs from 'node:fs';
-import path from 'node:path';
+import fs from 'fs';
+import path from 'path';
 import YINI from 'yini-parser';
 import { getSerializer } from '../serializers/index.js';
 import { debugPrint, printObject } from '../utils/print.js';
+import { assertInputAndOutputAreDifferent, printStderr, printStdout, printWarning, resolveStrictMode, } from './commonFunctions.js';
 // -------------------------------------------------------------------------
 /**
  * Will return true if:
@@ -12,7 +13,9 @@ import { debugPrint, printObject } from '../utils/print.js';
  *   * destination is newer than source
  * @returns
  */
-export const shouldSkipBecauseDestNewer = (file, optionOverwrite, 
+export const shouldSkipBecauseDestNewer = (
+// commandOptions: IParseCommandOptions,
+file, optionOverwrite, 
 // optionVerbose?: boolean | undefined,
 outputFile = '') => {
     if (outputFile && optionOverwrite === undefined) {
@@ -27,7 +30,7 @@ outputFile = '') => {
     }
     return false;
 };
-export const isAllowWriteOutput = (srcPath, destPath, newContent, overwrite) => {
+export const isAllowWriteOutput = (commandOptions, srcPath, destPath, newContent, overwrite) => {
     if (!fs.existsSync(destPath)) {
         return true;
     }
@@ -40,29 +43,31 @@ export const isAllowWriteOutput = (srcPath, destPath, newContent, overwrite) =>
     const srcStat = fs.statSync(srcPath);
     const destStat = fs.statSync(destPath);
     if (destStat.mtimeMs > srcStat.mtimeMs) {
-        reportAction('skip', destPath, `newer than source "${srcPath}"`);
+        reportAction(commandOptions, 'skip', destPath, `newer than source "${srcPath}"`);
         return false;
     }
     const existing = fs.readFileSync(destPath, 'utf-8');
     if (existing === newContent) {
-        reportAction('skip', destPath, 'output unchanged');
+        reportAction(commandOptions, 'skip', destPath, 'output unchanged');
         return false;
     }
     return true;
 };
-const reportAction = (action, file, reason) => {
-    let txt = '';
-    if (reason) {
-        txt = `${action.padEnd(6)} "${file}" (${reason})`;
-    }
-    else {
-        txt = `${action.padEnd(6)} "${file}"`;
-    }
+const reportAction = (options, action, file, reason) => {
+    if (options.silent)
+        return;
+    let txt = reason
+        ? `${action.padEnd(6)} "${file}" (${reason})`
+        : `${action.padEnd(6)} "${file}"`;
     if (action === 'skip') {
-        console.warn(txt);
+        if (!options.quiet) {
+            console.warn(txt);
+        }
     }
     else {
-        console.log(txt);
+        if (options.verbose && !options.quiet) {
+            console.log(txt);
+        }
     }
 };
 /*
@@ -89,7 +94,7 @@ const reportAction = (action, file, reason) => {
 
     Execution control:
     --fail-fast
-    --best-effort = ignore-errors within a file, attempt recovery and still emit outp
+    --best-effort = ignore-errors within a file, attempt recovery, and still emit output
                 --No for parse, --keep-going = continue to the next file when one fails
     --max-errors <n>
     --verbose
@@ -111,21 +116,20 @@ export const parseFile = (file, commandOptions) => {
     doParseFile(file, commandOptions, outputFormat, outputFile);
 };
 const resolveOutputFormat = (options) => {
-    if (options.js && options.compact) {
-        throw new Error('--js and --compact cannot be combined.');
+    const selected = [
+        options.json ? 'json' : null,
+        options.compact ? 'json-compact' : null,
+        options.js ? 'js' : null,
+        options.yaml ? 'yaml' : null,
+        options.xml ? 'xml' : null,
+    ].filter(Boolean);
+    if (selected.length > 1) {
+        throw new Error('Choose only one output format: --json, --compact, --js, --yaml, or --xml.');
     }
-    if (options.compact)
-        return 'json-compact';
-    if (options.js)
-        return 'js';
-    if (options.yaml)
-        return 'yaml';
-    if (options.xml)
-        return 'xml';
     if (options.pretty) {
-        console.warn('Warning: --pretty is deprecated. Use --json instead.');
+        printWarning(options, 'Warning: --pretty is deprecated. Use --json instead.');
     }
-    return 'json';
+    return selected[0] ?? 'json';
 };
 /**
  * Returns true if the parsed result appears to contain usable output data.
@@ -149,55 +153,94 @@ const hasMeaningfulParsedData = (value) => {
         return false;
     return Object.keys(value).length > 0;
 };
-const doParseFile = (file, commandOptions, outputFormat, outputFile = '') => {
-    debugPrint('File = ' + file);
-    debugPrint('outputFormat = ' + outputFormat);
-    const parseOptions = {
-        strictMode: commandOptions.strict ?? false,
-        failLevel: commandOptions.bestEffort ? 'ignore-errors' : 'auto',
-        includeMetadata: true,
-        includeDiagnostics: true,
-    };
-    // Check early if should skip before parsing,
-    // saves a lot of time in some cases.
-    if (shouldSkipBecauseDestNewer(file, commandOptions.overwrite, 
-    // commandOptions.verbose,
-    outputFile)) {
-        if (commandOptions.verbose) {
-            const resolved = path.resolve(outputFile);
-            reportAction('skip', resolved, `newer than source "${file}"`);
+const formatParserDiagnostics = (parsed) => {
+    const errors = parsed.meta?.diagnostics?.errors?.payload ?? [];
+    return errors.map((diagnostic) => {
+        if (typeof diagnostic === 'string') {
+            return diagnostic;
+        }
+        if (!diagnostic || typeof diagnostic !== 'object') {
+            return String(diagnostic);
         }
+        const issue = diagnostic;
+        const message = issue.message ?? issue.code ?? 'Unknown parser error';
+        const location = issue.line != null
+            ? `line ${issue.line}${issue.column != null ? `:${issue.column}` : ''}: `
+            : '';
+        return `${location}${String(message)}`;
+    });
+};
+const printParseFailure = (commandOptions, parsed) => {
+    const messages = formatParserDiagnostics(parsed);
+    if (messages.length === 0) {
+        printStderr(commandOptions, 'Syntax error: failed to parse YINI input.');
         return;
     }
+    for (const message of messages) {
+        const normalizedMessage = message.toLowerCase().includes('syntax error')
+            ? message
+            : `Syntax error: ${message}`;
+        printStderr(commandOptions, normalizedMessage);
+    }
+};
+const doParseFile = (file, commandOptions, outputFormat, outputFile = '') => {
+    debugPrint('File = ' + file);
+    debugPrint('outputFormat = ' + outputFormat);
     try {
+        const strictMode = resolveStrictMode(commandOptions);
+        const parseOptions = {
+            strictMode: strictMode,
+            failLevel: commandOptions.bestEffort ? 'ignore-errors' : 'auto',
+            includeMetadata: true,
+            includeDiagnostics: true,
+        };
+        // Check that output and input file are not the same.
+        if (outputFile) {
+            assertInputAndOutputAreDifferent(file, outputFile);
+        }
+        // Check early if should skip before parsing,
+        // saves a lot of time in some cases.
+        if (shouldSkipBecauseDestNewer(
+        // commandOptions,
+        file, commandOptions.overwrite, 
+        // commandOptions.verbose,
+        outputFile)) {
+            if (commandOptions.verbose) {
+                const resolved = path.resolve(outputFile);
+                reportAction(commandOptions, 'skip', resolved, `newer than source "${file}"`);
+            }
+            return;
+        }
         const parsedWithMeta = YINI.parseFile(file, parseOptions);
         const errorCount = parsedWithMeta?.meta?.diagnostics?.errors?.errorCount ?? 0;
         const parsedData = parsedWithMeta.result;
         const hasUsableOutput = hasMeaningfulParsedData(parsedData);
-        if (errorCount > 0 &&
-            !commandOptions.bestEffort &&
-            (commandOptions.strict || !hasUsableOutput)) {
+        const hasErrors = errorCount > 0;
+        const bestEffort = !!commandOptions.bestEffort;
+        const shouldFailHard = hasErrors && !bestEffort && (strictMode || !hasUsableOutput);
+        if (shouldFailHard) {
+            printParseFailure(commandOptions, parsedWithMeta);
             process.exit(1);
         }
         const serializer = getSerializer(outputFormat);
         const output = serializer.serialize(parsedData);
         if (outputFile) {
             const resolved = path.resolve(outputFile);
-            if (!isAllowWriteOutput(file, resolved, output, commandOptions.overwrite)) {
+            if (!isAllowWriteOutput(commandOptions, file, resolved, output, commandOptions.overwrite)) {
                 return;
             }
             fs.writeFileSync(resolved, output, 'utf-8');
             if (commandOptions.verbose) {
-                reportAction('write', resolved);
+                reportAction(commandOptions, 'write', resolved);
             }
         }
         else {
-            console.log(output);
+            printStdout(commandOptions, output);
         }
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        console.error(`Error: ${message}`);
+        printStderr(commandOptions, `Error: ${message}`);
         process.exit(1);
     }
 };

package/dist/commands/validateCommand.d.ts

@@ -1,5 +1,10 @@
 import { IGlobalOptions } from '../types.js';
 export interface IValidateCommandOptions extends IGlobalOptions {
     stats?: boolean;
+    warningsAsErrors?: boolean;
+    format?: 'json' | 'text';
+    failFast?: boolean;
+    recursive?: boolean;
+    maxErrors?: number;
 }
-export declare const validateFile: (file: string, commandOptions?: IValidateCommandOptions) => never;
+export declare const validateTargets: (targets: string[], options: IValidateCommandOptions) => never;