yini-cli 1.3.4-beta → 1.4.0

package/README.md

@@ -1,20 +1,13 @@
-# YINI-CLI
+# YINI CLI
 > **Readable configuration without indentation pitfalls or JSON verbosity.**  
 
-**The official terminal / command-line (CLI) tool for validating, inspecting, and converting YINI (by the YINI-lang project) configuration files to JSON or JavaScript.**
+**The official CLI for validating, inspecting, and converting YINI configuration files to JSON or JavaScript, built by the YINI-lang project.**
 
-*YINI is an INI-inspired and human-readable text format for representing structured information. It is designed to be clear, predictable, and easy for humans to read and write. It supports nesting, comments, and a formally defined syntax. It is suitable for configuration files, application settings, and general data-storage use cases.*
+*YINI is an INI-inspired, human-friendly configuration format with real 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)
+[![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) [![npm downloads](https://img.shields.io/npm/dm/yini-cli)](https://www.npmjs.com/package/yini-cli)
 
-This tool is designed for teams and developers working with human-edited configuration files who require explicit structure without indentation-based semantics.
-
----
-
-## Example of YINI code
-> A basic YINI configuration example, showing a section, nested section, comments:  
-![YINI Config Example](./samples/basic.yini.png)
-Source: [basic.yini](./samples/basic.yini)
+Designed for developers and teams who want human-edited configuration with explicit structure and no indentation-based semantics.
 
 ## Quick Start
 
@@ -23,7 +16,7 @@ YINI CLI requires Node.js **v20 or later**.
 
 ### Installation
 
-1. **Install it globally from npm — (requires Node.js)**  
+1. **Install globally from npm — (requires Node.js)**  
     Open your terminal and run:
     ```
     npm install -g yini-cli
@@ -34,22 +27,22 @@ YINI CLI requires Node.js **v20 or later**.
     ```bash
     yini --version
     ```
-    This should print the installed version (e.g., 1.0.0).
+    This should print the installed version.
 
-    Then you may try:
+    Then try:
     ```bash
     yini --help
     ```
-    Should show you the CLI help for YINI.
+    This should show the CLI help.
 
 3. **Test functionality**  
     Create a simple test file, for example: `config.yini`:
     ```yini
     ^ App
-      name = "My App Title"
-      version = "1.2.3"
-      pageSize = 25
-      darkTheme = off
+    name = "My App Title"
+    version = "1.2.3"
+    pageSize = 25
+    darkTheme = off
     ```
 
     Then run:
@@ -57,7 +50,7 @@ YINI CLI requires Node.js **v20 or later**.
     yini parse config.yini
     ```
 
-    Expected result, your CLI should output a parsed version of the config and output something similar to:
+    Expected output:
     ```json
     {
         "App": {
@@ -77,7 +70,12 @@ YINI CLI requires Node.js **v20 or later**.
 
 ---
 
-## Example 2
+## What YINI looks like
+> A basic YINI configuration example, showing a section, nested section, comments:  
+![YINI Config Example](./samples/basic.yini.png)
+Source: [basic.yini](./samples/basic.yini)
+
+### A larger example
 > A real-world YINI configuration example, showing sections, nesting, comments, and multiple data types:  
 ![YINI Config Example](./samples/config.yini.png)
 Source: [config.yini](./samples/config.yini)
@@ -86,10 +84,10 @@ Source: [config.yini](./samples/config.yini)
 
 ## 🙋‍♀️ Why YINI?
 - **Indentation-independent structure:** YINI is indentation-independent — whitespace never alters structural meaning.
-- **Explicit nesting & refactoring safety:** It uses clear header markers (`^`, `^^`, `^^^`) to define hierarchy (like in Markdown), without long dotted keys.
-- **Multiple data types:** Supports boolean literals (`true` / `false`, `Yes` / `No`, etc), numbers, arrays (lists), and JS-style objects natively, with explicit string syntax.
-- **Comments support:** YINI supports multiple comment styles (`#`, `//`, `/* ... */`, and `;`) allowing one to document config directly in the file.
-- **Predictable parsing rules:** Well-defined rules with optional strict and lenient modes, for different use-requirements.
+- **Explicit nesting:** It uses clear header markers (`^`, `^^`, `^^^`) to define hierarchy, making large configurations easier to scan and refactor.
+- **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.
+- **Predictable parsing:** Well-defined rules with optional strict and lenient modes for different use cases.
 
 ---
 
@@ -130,7 +128,7 @@ yini parse --help
 
 ---
 
-## Quick Look at YINI
+## A closer look at YINI
 
 Here's a small example showing YINI structure and comments:
 ```yini
@@ -149,7 +147,7 @@ Here's a small example showing YINI structure and comments:
     # This is a comment too.
 ```
 
-**The above YINI converted to a JS object:**
+**The above YINI as a JavaScript object:**
 ```js
 {
     App: {
@@ -201,9 +199,7 @@ The `parse` command supports multiple output formats:
 >💡 `--js` and `--compact` are mutually exclusive.  
 >💡 Tip: You can combine --output with any style flag to control both formatting and destination.
 
----
-
-## 📁 Output File Handling
+### Output File Handling
 
 When using `-o, --output <file>`, YINI CLI applies safe write rules:
 
@@ -211,45 +207,44 @@ When using `-o, --output <file>`, YINI CLI applies safe write rules:
 |----------|--------|
 | File does not exist | File is written |
 | File exists and is **older** than the input YINI file | File is overwritten |
-| File exists and is **newer** than the input YINI file | Command fails |
+| File exists and is **newer** than the input YINI file | Skipped by default |
+| File exists and output content is unchanged | Skipped |
 | `--overwrite` is used | File is always overwritten |
 | `--no-overwrite` is used | Command fails if file exists |
 
-This prevents accidental overwriting of newer generated files.
+This helps avoid overwriting newer generated files and avoids rewriting unchanged output unnecessarily.
 
-Use:
-`--overwrite` to force replacement.
+Use `--overwrite` to force replacement.
 
 ---
 
-## 🛠 Roadmap
-Areas of planned and possible future expansion:
+## Links
+- ➡️ [YINI Homepage](https://yini-lang.org)  
+  *Tutorials, guides, and examples.*
 
-1. **Improve existing commands** — Continued functionality improvements, better diagnostics, and expanded QA for `parse` and `validate` and their options.
-2. Command `convert`: Batch convert YINI files to JSON or JavaScript.
-3. Command `format`: Pretty-print or normalize a `.yini` file.
-4. Command `lint`: Stricter stylistic checks (like `validate`, but opinionated).
-5. Command `diff`: Compare two YINI files and show structural/config differences.
-6. Import JSON or XML into YINI format.
+- ➡️ [Read the YINI Specification](https://yini-lang.org/refs/specification)  
+  *Full syntax and format reference.*
 
----
-
-## Links
 - ➡️ [YINI Parser on npm](https://www.npmjs.com/package/yini-parser)  
-  *Install and view package details.*
+  *The TypeScript/Node.js parser used by this CLI.*
 
-- ➡️ [YINI Project](https://github.com/YINI-lang)  
-  *YINI home on GitHub.*
+- ➡️ [Demo Apps](https://github.com/YINI-lang/yini-demo-apps/tree/main)  
+  *Complete basic usage examples.*
+
+- ➡️ [YINI-lang Project](https://github.com/YINI-lang)  
+  *Repositories and related ecosystem projects.*
 
 ---
 
-## Contribution & Involvement
-Contributions, issues, and feedback are welcome. Even small improvements or suggestions are appreciated.
+## Contributing
+Contributions, bug reports, and feedback are welcome. Even small improvements or suggestions are appreciated.  
+
+If this tool is useful to you, a GitHub star helps more people discover the project and supports future development.
 
 ---
 
 ## License
-This project is licensed under the Apache-2.0 license - see the [LICENSE](<./LICENSE>) file for details.
+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`.
 
@@ -258,4 +253,4 @@ In this project on GitHub, the `libs` directory contains third party software an
 **^YINI ≡**  
 > Readable like INI. Structured like JSON. No indentation surprises.  
 
-[yini-lang.org](https://yini-lang.org/?utm_source=github&utm_medium=referral&utm_campaign=yini_cli&utm_content=readme_footer) · [YINI on GitHub](https://github.com/YINI-lang)  
+[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

@@ -4,6 +4,7 @@ import path from 'node: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.
@@ -152,52 +156,61 @@ const hasMeaningfulParsedData = (value) => {
 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}"`);
-        }
-        return;
-    }
     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 strictMode = resolveStrictMode(commandOptions)
+        const shouldFailHard = hasErrors && !bestEffort && (strictMode || !hasUsableOutput);
+        if (shouldFailHard) {
             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;