yini-cli 1.0.0-alpha.2

package/prettier.config.cjs

@@ -0,0 +1,33 @@
+// prettier.config.js
+/** @type {import("prettier").Config} */
+module.exports = {
+  // ────────────────────────────────────────────────────────────────
+  // Formatting Options
+  // ─
+  useTabs: false,
+
+  // Maximum line length before Prettier wraps.
+  // "printWidth": 120,
+  printWidth: 80,
+
+  // Number of spaces per indentation level.
+  tabWidth: 4,
+  singleQuote: true,
+  trailingComma: "all",
+  jsxBracketSameLine: true,
+  semi: false,
+// Whether to add a space between brackets in object literals
+  bracketSpacing: true,
+  // Since prettier 3.0, manually specifying plugins is required
+  plugins: ['@ianvs/prettier-plugin-sort-imports'],
+  // This plugin's options
+    importOrder: [
+    '^react$',                 // Put React first
+    '<THIRD_PARTY_MODULES>',   // Then other external dependencies
+    '^[@/](.*)$',              // Then “@/…” or “@alias/…” imports
+    '^[./]',                   // Then relative imports
+  ],
+  importOrderParserPlugins: ['typescript', 'jsx', 'decorators-legacy'],
+  importOrderTypeScriptVersion: '5.0.0',
+  importOrderCaseSensitive: false,
+}

package/sample.yini

@@ -0,0 +1,19 @@
+@YINI
+
+/*
+    Example of a YINI document.
+*/
+
+^ Service               // Defines a section named Server.
+Enabled = true
+
+    ^^ Cache
+    Type = "redis"          // Defines Cache, a sub-section of Server.
+    TTL = 3600
+
+        ^^^ Options             // Defines Options, a sub-section of Cache.
+        Host = "127.0.0.1"
+        Port = 6379
+
+^ Env                   // Defines a section named Env.
+code = "dev"

package/samples/basic.yini

@@ -0,0 +1,11 @@
+@yini
+
+^ App
+title = 'My App'
+items = 10
+debug = ON
+
+^ Server
+host = "localhost"
+port = 8080
+useTLS = OFF

package/samples/nested.yini

@@ -0,0 +1,26 @@
+/*
+    nested.yini
+    Demonstrates nested sections in YINI format.
+*/
+
+@yini
+
+^ App                  // Top-level section: App
+name = 'Nested Demo App'
+version = "1.2.3"
+
+    ^^ Theme           // Nested under App: App.Theme
+    primaryColor = #336699
+    darkMode = true
+
+
+        ^^^ Overrides  // Nested under Theme: App.Theme.Overrides
+        darkMode = false
+        fontSize = 14
+
+^ Database             // Another top-level section: Database
+host = "db.local"
+port = 5432
+
+    ^^ Credentials     // Nested under Database: Database.Credentials    username = "admin"
+    password = "secret"

package/src/commands/info.ts

@@ -0,0 +1,19 @@
+// import pkg from '../../package.json'
+import { createRequire } from 'module'
+
+const require = createRequire(import.meta.url)
+const pkg = require('../../package.json')
+
+// import pkg from '../../package.json' assert { type: 'json' }
+
+export const printInfo = () => {
+    console.log(`** YINI CLI **`)
+    console.log(`yini-cli:    ${pkg.version}`)
+    console.log(
+        `yini-parser: ${pkg.dependencies['yini-parser'].replace('^', '')}`,
+    )
+    console.log(`Author:      ${pkg.author}`)
+    console.log(`License:     ${pkg.license}`)
+    console.log(`Homepage:    ${pkg.homepage}`)
+    console.log('Repo:        https://github.com/YINI-lang/yini-cli')
+}

package/src/commands/parse.ts

@@ -0,0 +1,88 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import util from 'util'
+import YINI from 'yini-parser'
+import { ICLIParseOptions, TBailSensitivity } from '../types.js'
+import { printObject, toPrettyJSON } from '../utils/print.js'
+
+type TOutputStype = 'JS-style' | 'Pretty-JSON' | 'Console.log' | 'JSON-compact'
+
+export const parseFile = (file: string, options: ICLIParseOptions) => {
+    const outputFile = options.output || ''
+    const isStrictMode = !!options.strict
+    let outputStyle: TOutputStype = 'JS-style'
+
+    console.log('file = ' + file)
+    console.log('output = ' + options.output)
+    console.log('options:')
+    printObject(options)
+
+    if (options.pretty) {
+        outputStyle = 'Pretty-JSON'
+    } else if (options.log) {
+        outputStyle = 'Console.log'
+    } else if (options.json) {
+        outputStyle = 'JSON-compact'
+    } else {
+        outputStyle = 'JS-style'
+    }
+
+    doParseFile(file, outputStyle, isStrictMode, outputFile)
+}
+
+const doParseFile = (
+    file: string,
+    outputStyle: TOutputStype,
+    isStrictMode = false,
+    outputFile = '',
+) => {
+    // let strictMode = !!options.strict
+    let bailSensitivity: TBailSensitivity = 'auto'
+    let includeMetaData = false
+
+    console.log('File = ' + file)
+    console.log('outputStyle = ' + outputStyle)
+
+    // try {
+    // const raw = fs.readFileSync(file, 'utf-8')
+    // const parsed = YINI.parseFile(
+    //const parsed = YINI.parseFile(file)
+    const parsed = YINI.parseFile(
+        file,
+        isStrictMode,
+        bailSensitivity,
+        includeMetaData,
+    )
+    // const parsed = YINI.parse(raw)
+
+    // const output = options.pretty
+    //     ? // ? JSON.stringify(parsed, null, 2)
+    //       toPrettyJSON(parsed)
+    //     : JSON.stringify(parsed)
+    let output = ''
+    switch (outputStyle) {
+        case 'Pretty-JSON':
+            output = toPrettyJSON(parsed)
+            break
+        case 'Console.log':
+            output = '<todo>'
+            break
+        case 'JSON-compact':
+            output = JSON.stringify(parsed)
+            break
+        default:
+            output = util.inspect(parsed, { depth: null, colors: false })
+    }
+
+    if (outputFile) {
+        // Write JSON output to file instead of stdout.
+        fs.writeFileSync(path.resolve(outputFile), output, 'utf-8')
+        console.log(`Output written to ${outputFile}`)
+    } else {
+        console.log(output)
+    }
+    // } catch (err: any) {
+    //     console.error(`Error: ${err.message}`)
+    //     process.exit(1)
+    // }
+}

package/src/commands/validate.ts

@@ -0,0 +1,48 @@
+import fs from 'node:fs'
+import { exit } from 'node:process'
+import YINI from 'yini-parser'
+import { printObject } from '../utils/print.js'
+
+interface IValidateOptions {
+    strict?: boolean
+    details?: boolean
+    silent?: boolean
+}
+
+export const validateFile = (file: string, options: IValidateOptions = {}) => {
+    try {
+        const content = fs.readFileSync(file, 'utf-8')
+        const isMeta = true
+        const parsed = YINI.parse(
+            content,
+            options.strict ?? false,
+            'auto',
+            isMeta,
+        )
+
+        if (!options.silent) {
+            console.log(
+                `✔ File is valid${options.strict ? ' (strict mode)' : ''}.`,
+            )
+
+            if (options.details) {
+                //@todo format parsed.meta to details as
+                /*
+                 * Details:
+                 * - YINI version: 1.0.0-beta.6
+                 * - Mode: strict
+                 * - Keys: 42
+                 * - Sections: 6
+                 * - Nesting depth: 3
+                 * - Has @yini: true
+                 */
+
+                printObject(parsed.meta)
+            }
+        }
+        exit(0)
+    } catch (err: any) {
+        console.error(`✖ Validation failed: ${err.message}`)
+        exit(1)
+    }
+}

package/src/config/env.ts

@@ -0,0 +1,85 @@
+/**
+ * NODE_ENV - Defacto Node.js modes (environments)
+ *
+ * Used in many JS frameworks and tools, for special purposes.
+ * Some even only know 'production' and treat everything else as 'development'.
+ * Also Jest sets NODE_ENV automatically to 'test'.
+ */
+type TNodeEnv = 'development' | 'production' | 'test'
+
+/**
+ * APP_ENV - More custom envs (more finer-grained control) for this project.
+ * @note Since this is a library (as opposed to a Web/App), we don't use "staging".
+ */
+type TAppEnv = 'local' | 'ci' | 'production' // Note: 'staging' is omitted by purpose.
+
+const localNodeEnv = (process.env.NODE_ENV || 'production') as TNodeEnv
+const localAppEnv = (process.env.APP_ENV || 'production') as TAppEnv
+
+// export const initEnvs = () => {
+//     const localNodeEnv = (process.env.NODE_ENV || 'production') as TNodeEnv
+//     const localAppEnv = (process.env?.APP_ENV || 'production') as TAppEnv
+
+//     return { localNodeEnv, localAppEnv }
+// }
+
+// const { localNodeEnv, localAppEnv } = initEnvs()
+
+/** Are we running in the environment "development"? Will be based on the (global) environment variable process.env.NODE_ENV. */
+export const isDevEnv = (): boolean => localNodeEnv === 'development'
+
+/** Are we running in the environment "production"? Will be based on the (global) environment variable process.env.NODE_ENV. */
+export const isProdEnv = (): boolean => localNodeEnv === 'production'
+
+/** Are we running in the environment "test"? Will be based on the (global) variable process.env.NODE_ENV. */
+export const isTestEnv = (): boolean => localNodeEnv === 'test'
+
+/** Will be based on the local argument when this process was launched.
+ * @returns True if the DEV flag is set.
+ * @example npm run start -- isDev=1
+ * @example node dist/index.js isDev=1
+ */
+export const isDev = (): boolean => {
+    const len = process.argv.length
+
+    // NOTE: We will start with index 2, since the first element will be
+    // execPath. The second element will be the path to the
+    // JavaScript file being executed.
+    for (let i = 2; i < len; i++) {
+        const val: string = process.argv[i] || ''
+        if (
+            val.toLowerCase() === 'isdev=1' ||
+            val.toLowerCase() === 'isdev=true'
+        ) {
+            return true
+        }
+    }
+
+    return false
+}
+
+/** Will be based on the local argument when this process was launched.
+ * @returns True if the DEBUG flag is set.
+ * @example npm run start -- isDebug=1
+ * @example node dist/index.js isDebug=1
+ */
+export const isDebug = (): boolean => {
+    const len = process.argv.length
+
+    // NOTE: We will start with index 2, since the first element will be
+    // execPath. The second element will be the path to the
+    // JavaScript file being executed.
+    for (let i = 2; i < len; i++) {
+        const val: string = process.argv[i] || ''
+        if (
+            val.toLowerCase() === 'isdebug=1' ||
+            val.toLowerCase() === 'isdebug=true'
+        ) {
+            return true
+        }
+    }
+
+    return false
+}
+
+export { localNodeEnv, localAppEnv }

package/src/descriptions.ts

@@ -0,0 +1,6 @@
+export const descriptions = {
+    yini: 'CLI for parsing and validating YINI config files',
+    'For-command-info': 'Show extended information (details, links, etc.)',
+    'For-command-parse': 'Parse a YINI file and print the result',
+    'For-command-validate': 'Checks if the file can be parsed as valid YINI',
+}

package/src/index.ts

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// (!) NOTE: Leave above shebang as first line!
+
+// import pkg from '../package.json'
+import { createRequire } from 'module'
+import { Command } from 'commander'
+import { printInfo } from './commands/info.js'
+import { parseFile } from './commands/parse.js'
+import { validateFile } from './commands/validate.js'
+import { isDebug } from './config/env.js'
+import { descriptions as descripts } from './descriptions.js'
+import { debugPrint, toPrettyJSON } from './utils/print.js'
+
+const require = createRequire(import.meta.url)
+const pkg = require('../package.json')
+
+const program = new Command()
+
+/*
+
+Idea/suggestion
+yini [parse] [--strict] [--pretty] [--output]
+
+Current suggestion:
+* yini parse config.yini
+	JS-style object using printObject()
+	to stdout
+* yini parse config.yini --pretty
+	Pretty JSON	using JSON.stringify(obj, null, 4)
+	to stdout
+* yini parse config.yini --output out.txt
+	JS-style object	
+	to out.txt
+* yini parse config.yini --pretty --output out.json
+	Pretty JSON	
+	to out.json
+
+New suggestion:
+Current suggestion:
+* yini parse config.yini
+	JS-style object using printObject(obj) (using using util.inspect)
+	to stdout
+* yini parse config.yini --pretty
+	Pretty JSON	using JSON.stringify(obj, null, 4) (formatted, readable)
+	to stdout
+* yini parse config.yini --log
+	Intended for quick output using console.log (nested object may get compacted/abbreviate)
+	to stdout
+* yini parse config.yini --json
+	Stringigies JSON using using JSON.stringify(obj) (compact, machine-parseable)
+	to stdout
+* yini parse config.yini --output out.txt
+	JS-style object	
+	to out.txt
+* yini parse config.yini --pretty --output out.json
+	Pretty JSON	
+	to out.json
+
+*/
+
+// Display help for command
+program.name('yini').description(descripts.yini).version(pkg.version)
+
+program.addHelpText(
+    'before',
+    `YINI CLI (Yet another INI)
+
+For parsing and validating YINI configuration files.
+A human-friendly config format - like INI, but with type-safe values,
+nested sections, comments, minimal syntax noise, and optional strict mode.
+
+Crafted for clarity, consistency, and the simple joy of it. :)`,
+)
+program.addHelpText(
+    'after',
+    `
+Examples:
+  $ yini parse config.yini
+  $ yini validate config.yini --strict
+  $ yini parse config.yini --pretty --output out.json
+
+More info: https://github.com/YINI-lang/yini-parser
+`,
+)
+
+//program.command('help [command]').description('Display help for command')
+
+// Command info
+program
+    .command('info')
+    // .command('')
+    .description(descripts['For-command-info'])
+    // .option('info')
+    .action((options) => {
+        debugPrint('Run command "info"')
+        if (isDebug()) {
+            console.log('options:')
+            console.log(toPrettyJSON(options))
+        }
+        printInfo()
+    })
+
+/**
+ *
+ * Maybe later, to as default command: parse <parse>
+ */
+// program
+//     .argument('<file>', 'File to parse')
+//     .option('--strict', 'Parse YINI in strict-mode')
+//     .option('--pretty', 'Pretty-print output as JSON')
+//     // .option('--log', 'Use console.log output format (compact, quick view)')
+//     .option('--json', 'Compact JSON output using JSON.stringify')
+//     .option('--output <file>', 'Write output to a specified file')
+//     .action((file, options) => {
+//         if (file) {
+//             parseFile(file, options)
+//         } else {
+//             program.help()
+//         }
+//     })
+
+// Explicit "parse" command
+program
+    .command('parse <file>')
+    .description(descripts['For-command-parse'])
+    .option('--strict', 'Parse YINI in strict-mode')
+    .option('--pretty', 'Pretty-print output as JSON')
+    // .option('--log', 'Use console.log output format (compact, quick view)')
+    .option('--json', 'Compact JSON output using JSON.stringify')
+    .option('--output <file>', 'Write output to a specified file')
+    .action((file, options) => {
+        debugPrint('Run command "parse"')
+        debugPrint(`<file> = ${file}`)
+        if (isDebug()) {
+            console.log('options:')
+            console.log(toPrettyJSON(options))
+        }
+        if (file) {
+            parseFile(file, options)
+        } else {
+            program.help()
+        }
+    })
+
+/**
+ * To handle command validate, e.g.:
+ *      yini validate config.yini
+ *      yini validate config.yini --strict
+ *      yini validate config.yini --details
+ *      yini validate config.yini --silent
+ *
+ * If details:
+ * Details:
+ * - YINI version: 1.0.0-beta.6
+ * - Mode: strict
+ * - Keys: 42
+ * - Sections: 6
+ * - Nesting depth: 3
+ * - Has @yini: true
+ */
+program
+    .command('validate <file>')
+    .description(descripts['For-command-validate'])
+    .option('--strict', 'Enable parsing in strict-mode')
+    .option(
+        '--details',
+        'Print detailed meta-data info (e.g., key count, nesting, etc.)',
+    )
+    .option('--silent', 'Suppress output')
+    .action((file, options) => {
+        //@todo add debugPrint
+        if (file) {
+            validateFile(file, options)
+        } else {
+            program.help()
+        }
+    })
+
+// NOTE: Converting YINI files to other formats than json and js.
+// Other format should go into a new CLI-command called 'yini-convert'.
+
+program.parseAsync()

package/src/types.ts

@@ -0,0 +1,9 @@
+export interface ICLIParseOptions {
+    strict?: boolean
+    pretty?: boolean
+    log?: boolean
+    json?: boolean
+    output?: string
+}
+
+export type TBailSensitivity = 'auto' | 0 | 1 | 2

package/src/utils/print.ts

@@ -0,0 +1,49 @@
+/**
+ * This file contains general system helper functions (utils).
+ * @note More specific YINI helper functions should go into yiniHelpers.ts-file.
+ */
+import util from 'util'
+import { isDebug, isDev, isProdEnv, isTestEnv } from '../config/env.js'
+
+// import { isDebug, isDev, isProdEnv, isTestEnv } from '../config/env'
+
+export const debugPrint = (str: any = '') => {
+    isDebug() && console.debug('DEBUG: ' + str)
+    console.debug('DEBUG: ' + str)
+}
+
+export const devPrint = (str: any = '') => {
+    isDev() && !isTestEnv() && console.log('DEV: ' + str)
+    console.log('DEV: ' + str)
+}
+
+export const toJSON = (obj: any): string => {
+    const str = JSON.stringify(obj)
+    return str
+}
+
+export const toPrettyJSON = (obj: any): string => {
+    const str = JSON.stringify(obj, null, 4)
+    return str
+}
+
+/** Pretty-prints a JavaScript object as formatted JSON to the console.
+ * Strict JSON, all keys are enclosed in ", etc.
+ */
+export const printJSON = (obj: any) => {
+    if (isProdEnv() || (isTestEnv() && !isDebug())) return
+
+    const str = toPrettyJSON(obj)
+    console.log(str)
+}
+
+/**
+ * Print a full JavaScript object in a human-readable way (not as JSON).
+ * Not strict JSON, and shows functions, symbols, getters/setters, and class names.
+ * @param isColors If true, the output is styled with ANSI color codes.
+ */
+export const printObject = (obj: any, isColors = true) => {
+    if (isProdEnv() || (isTestEnv() && !isDebug())) return
+
+    console.log(util.inspect(obj, { depth: null, colors: isColors }))
+}

package/tests/fixtures/corrupt-config-1.yini

@@ -0,0 +1,8 @@
+/*
+    corrupt yini
+    In strict should throw error while lenient should pass (given that bailSensitivity = 'auto').
+*/
+
+^ Section
+value = 42
+333 = "missing key name"	// (!) Invalid key!

package/tests/fixtures/invalid-config-1.yini

@@ -0,0 +1,2 @@
+<garbage-content-in-this-file>
+

package/tests/fixtures/nested-config-1.yini

@@ -0,0 +1,7 @@
+@yini
+
+^ App
+name = "Nested"
+
+    ^^ Database
+    host = "localhost"

package/tests/fixtures/valid-config-1.yini

@@ -0,0 +1,5 @@
+@yini
+
+^ App
+title = "My App"
+enabled = ON