yini-cli 1.4.0 → 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) [![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)
+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/parseCommand.js

@@ -1,6 +1,6 @@
 // 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';
@@ -153,6 +153,36 @@ const hasMeaningfulParsedData = (value) => {
         return false;
     return Object.keys(value).length > 0;
 };
+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);
@@ -187,9 +217,9 @@ const doParseFile = (file, commandOptions, outputFormat, outputFile = '') => {
         const hasUsableOutput = hasMeaningfulParsedData(parsedData);
         const hasErrors = errorCount > 0;
         const bestEffort = !!commandOptions.bestEffort;
-        // const strictMode = resolveStrictMode(commandOptions)
         const shouldFailHard = hasErrors && !bestEffort && (strictMode || !hasUsableOutput);
         if (shouldFailHard) {
+            printParseFailure(commandOptions, parsedWithMeta);
             process.exit(1);
         }
         const serializer = getSerializer(outputFormat);

package/dist/index.js

@@ -79,7 +79,7 @@ const parseCmd = program
     .option('--yaml', 'Output as YAML.')
     .option('--xml', 'Output as XML.')
     // File handling options.
-    .option('-o, --output <file>', 'Write output to <file>. By default, an existing file is only overwritten if it is older than the input YINI file.')
+    .option('-o, --output <file>', 'Write output to <file>. By default, an existing output file is only overwritten if it is older than the input YINI file.')
     .option('--overwrite', 'Always overwrite the output file, even if it is newer than the input YINI file.')
     .option('--no-overwrite', 'Fail if the output file already exists.')
     // Behavior options.

package/docs/CHANGELOG.md

@@ -0,0 +1,130 @@
+# CHANGELOG
+
+## 1.5.0 - 2026 June
+- Bumped dependency `yini-parser` to `^1.6.0` with YINI Specification RC 6 parser support, which brings:
+  - Improved parser diagnostics and structured issue reporting.
+  - Support for the latest **RC 6** mode-declaration behavior.
+  - Improved handling of duplicate sections and duplicate keys.
+  - Improved section marker parsing, including marker separators.
+  - Improved string concatenation validation.
+  - Improved EOF handling for files without a final trailing newline.
+  - And more.
+
+- **Improved:** Included `docs/CHANGELOG.md` in the package.
+- Fixed CLI parse error reporting so parse failures are printed by `yini-cli` instead of relying on the parser library to write diagnostics directly to `stderr`.
+- Updated validation behavior to support the newer parser diagnostics model, including `passed-with-warnings` results for valid files that produce warnings.
+- Updated tests and fixtures for the newer parser behavior, including coverage for valid files without a final newline at EOF.
+- Confirmed that `yini-cli` remains quiet by default for JSON validation output, while text-mode validation still reports user-facing diagnostics where appropriate.
+
+## 1.4.0 - 2026 Apr
+- Bumped dependency `yini-parser` to `^1.5.0` which brings:
+  - **Updated** to match **YINI Specification RC.5**: includes synced grammar files and the latest section-header parsing rules.
+  - **Stricter**, more predictable strict mode: now requires exactly one explicit top-level section and a closing `/END` terminator.
+  - **Improved** parser reliability overall: better handling of null/empty values, cleaner `throwOnError` behavior, and expanded validation and test coverage.
+- **Added:** New `validate` command.
+  ```txt
+  Validate one or more YINI files.
+
+  <file>       Validate a single file.
+  <directory>  Validate all .yini files in the directory.
+
+  You can provide multiple files and directories, separated by spaces.
+
+  Options:
+    --warnings-as-errors  Treat warnings as errors for exit code purposes.
+    --stats               In text mode, stats only shown when file mode validates exactly one file.
+    --format <type>       Output format for validation results: text | json (choices: "text", "json",
+                          default: "text")
+    --fail-fast           Stop after first file that fails validation.
+    --max-errors <n>      Stop after N total errors (across files).
+    --no-recursive        Do not scan subdirectories.
+    -h, --help            Display full help for all commands.
+  ```
+- **Changed:** The short flag for strict mode is now `-S` (capital). Lowercase `-s` is now reserved for `--silent`, which aligns better with common CLI conventions.
+- **Improved:** Improved the usability of the `parse` command.
+- **Improved:** Test fixtures and CLI tests were reorganized for better clarity, separation, and Windows-safe argument handling.
+
+## 1.3.4 - 2026 Apr
+- **Promoted** YINI CLI is now considered stable (non-beta) after iterative beta releases and refinements.
+- **Fixed:** Rebuilt the project and reduced reported from 9 vulnerabilities (5 moderate, 4 high) to 0.
+- **Updated:** Bumped dependency `yini-parser` to `^1.4.3`.
+
+## 1.3.4-beta - 2026 Mar
+- **Updated:** Bumped dependency `yini-parser` to `^1.4.3-beta` that consists of:
+  - Fixed: Error messages and thrown parse errors now include correct line and column information again.
+  - Improved: Syntax and string-related parse errors are now clearer and more consistent.
+  - Improved: Reduced some duplicate follow-up errors during recovery after invalid input.
+
+## 1.3.3-beta - 2026 Mar
+- **Updated:** Bumped dependency `yini-parser` to `^1.4.2-beta`.
+
+## 1.3.2-beta - 2026 Mar
+- **Updated:** Bumped dependency `yini-parser` to `^1.4.1-beta`.
+- **Fixed:** `parse` now returns a non-zero exit code for invalid input that does not produce usable parsed output.
+- **Improved:** Better alignment with the latest parser diagnostics and recovery behavior.
+- **Improved:** `parse` command file output behavior.
+  - Added fast pre-check to skip parsing when the destination is newer than the source.
+  - Centralized output write policy and skip detection.
+- **Improved:** Avoid unnecessary file rewrites when generated output is unchanged.
+
+## 1.3.1-beta - 2026 Mar
+- **Improved:** `parse` command file write policy.
+  - Destination files newer than the source are now **skipped with a warning** instead of causing an error.
+  - Helps prevent unnecessary build failures in CI pipelines and static site generators (e.g. Astro).
+- **Improved:** Output files are only rewritten when the generated content has actually changed, reducing redundant file writes.
+
+## 1.3.0-beta - 2026 Mar
+- **Updated:** Bumped dependency `yini-parser` to `^1.4.0-beta`.
+- **Added:** CLI now supports parsing/validating **Classic (C) strings** (escape sequences) via the updated parser.
+- **Note:** Default (raw) strings are unchanged (backslashes `\` and `\n` remain as-is unless using `c"..."` / `C'...'`).
+- **Added:** New output formats for the `parse` command:
+  - `--yaml` to export parsed data as **YAML**
+  - `--xml` to export parsed data as **XML**
+- **Refactored:** Output format handling internally to improve robustness, simplify debugging, and make the code easier to test and maintain.
+
+## 1.2.1-beta - 2026 Feb
+- **Improved:** `validate` command:
+  - Strengthened `validate` command diagnostics handling and metadata guards.
+  - Replaced unsafe internal assertions with controlled error handling.
+  - Improved silent mode behavior and exit code consistency.
+
+## 1.2.0-beta - 2026 Feb
+- **Improved:** Updated `--help` to display full help for all commands, while preserving command-specific help through `yini help <command>`.
+- **Changed:** Showing extended information now uses the `info` command only. The global `--info` option has been removed — please use `yini info` instead.
+- **Updated:** `parse` command:
+  - Deprecated `--pretty` (JSON is now the default; use `--json` explicitly if desired).
+  - `--compact` now outputs compact JSON (no whitespace).
+  - Added `--js` option to output JavaScript-style objects.
+  - Improved `--output` file handling:
+    - By default, the output file is written only if it does not exist or is older than the source YINI file.
+    - Added `--overwrite` to always replace existing files.
+    - Added `--no-overwrite` to prevent replacing existing files.
+
+## 1.1.1-beta - 2025 Dec
+- **Updated:** Updated to use the latest YINI Parser version `1.3.2-beta` from `1.3.0-beta`.
+
+## 1.1.0-beta - 2025 Sep
+- **New command:** New command `validate` to validate parsing of a YINI file.
+- **Added** --strict as global option, to enable parsing in strict mode.
+- **Added** -q, --quiet as global option, to reduce output (show only errors).
+- **Added** --silent as global option, will suppress all output (even errors, exit code only).
+- **CI/Tooling (GitHub Actions):** Added security and quality checks:
+  - **Security:** CodeQL, dependency checke (`npm audit`) + lockfile-lint, Gitleaks (SARIF), Semgrep (SARIF).
+  - **CI CLI test**.
+  - **Regression tests:** run across a Node/OS matrix.
+  - **Releases:** npm publish with provenance (tag-driven).
+- Removed per-command --strict flags.
+
+## 1.0.3-beta - 2025 Sep
+- **Updated:** Now uses latest `yini-parser` library `v1.1.0-beta`, for greatly improved parsing, compatibility, and error handling with more descriptive and accurate error messages.
+
+## 1.0.2-beta - 2025 Aug
+- Bumped internal YINI Parser library to version 1.0.2-beta, which fixes and improves number parsing to fully support negative values and edge cases for integers, floats, hexadecimal, binary, octal, duodecimal, and exponential numbers.
+- Added this file into the repo.
+
+---
+
+**^YINI ≡**  
+> A simple, structured, and human-friendly configuration format.  
+
+[yini-lang.org](https://yini-lang.org) · [YINI on GitHub](https://github.com/YINI-lang)  

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "yini-cli",
-    "version": "1.4.0",
-    "description": "Official YINI CLI for validating, parsing, and converting a human-friendly config format with real structure, nested sections, and predictable strict or lenient parsing.",
+    "version": "1.5.0",
+    "description": "Official command-line tool for validating and converting YINI files — YINI is an INI-inspired, human-readable configuration format with explicit structure and predictable parsing.",
     "keywords": [
         "yini",
         "cli",
@@ -26,19 +26,20 @@
         }
     },
     "bin": {
-        "yini": "./dist/index.js"
+        "yini": "dist/index.js"
     },
     "homepage": "https://yini-lang.org/",
     "license": "Apache-2.0",
     "files": [
         "dist/",
         "README.md",
+        "docs/CHANGELOG.md",
         "LICENSE",
         "sample.yini"
     ],
     "repository": {
         "type": "git",
-        "url": "https://github.com/YINI-lang/yini-cli.git"
+        "url": "git+https://github.com/YINI-lang/yini-cli.git"
     },
     "private": false,
     "scripts": {
@@ -51,7 +52,7 @@
         "run:parse": "npm run start -- parse sample.yini",
         "run:validate": "npm run start -- validate sample.yini",
         "test:smoke": "vitest tests/smoke",
-        "test:general": "vitest tests/general",
+        "test:general": "vitest tests/global-options.test.ts",
         "test": "vitest run",
         "test:debug": "cross-env isDebug=1 vitest run --reporter=verbose",
         "test:general:debug": "cross-env isDebug=1 npm run test:general",
@@ -63,7 +64,7 @@
         "format": "prettier --check .",
         "format:fix": "prettier --write .",
         "build": "tsc",
-        "clean": "rm -rf dist",
+        "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
         "prepare": "npm run build",
         "prepublishOnly": "npm run lint && npm test && npm run build"
     },
@@ -72,12 +73,12 @@
         "commander": "^14.0.1",
         "xmlbuilder2": "^4.0.3",
         "yaml": "^2.8.2",
-        "yini-parser": "^1.5.0"
+        "yini-parser": "^1.6.0"
     },
     "devDependencies": {
         "@eslint/js": "^9.31.0",
         "@ianvs/prettier-plugin-sort-imports": "^4.4.2",
-        "@types/node": "^22.15.3",
+        "@types/node": "^22.19.19",
         "@typescript-eslint/eslint-plugin": "^8.37.0",
         "@typescript-eslint/parser": "^8.37.0",
         "cross-env": "^7.0.3",
@@ -87,7 +88,7 @@
         "execa": "^9.6.0",
         "husky": "^9.1.7",
         "lint-staged": "^16.0.0",
-        "nyc": "^17.1.0",
+        "nyc": "^18.0.0",
         "prettier": "^3.5.3",
         "tsx": "^4.7.0",
         "typescript": "^5.8.3",
@@ -95,10 +96,10 @@
     },
     "lint-staged": {
         "src/**/*.{js,jsx,json,ts,tsx,css,scss}": [
-            "prettier --config ./.prettierrc --write"
+            "prettier --config ./prettier.config.cjs --write"
         ]
     },
     "engines": {
-        "node": ">=13"
+        "node": ">=18"
     }
 }