@rzl-zone/build-tools 0.0.10 → 0.0.12-beta.0

package/dist/utils/server.d.ts

@@ -2,13 +2,14 @@
 * ========================================================================
 *  @rzl-zone/build-tools
 * ------------------------------------------------------------------------
-*  Version: `0.0.10`
+*  Version: `0.0.12-beta.0`
 *  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/build-tools`
 * ========================================================================
 */
 
-import { n as PatternOptions, r as defaultPatternOptions, t as PatternConfig } from "../fast-globe-options-CZ-9wIKV.js";
+import { t as AnyString } from "../extra-B1CzOGop.js";
+import { n as PatternOptions, r as defaultPatternOptions, t as PatternConfig } from "../fast-globe-options-DDloBj5e.js";
 import _fastGlob from "fast-glob";
 import _fsExtra from "fs-extra";
 type Icons = { readonly [K in keyof typeof emojiIcons]: string };
@@ -81,6 +82,435 @@ declare const emojiIcons: {
 *
 */
 declare const ICONS: Readonly<Icons>;
+/** -------------------------------------------------------------------
+* * ***Determines whether an option value comes from the default configuration
+* or has been explicitly overridden by the user.***
+* -------------------------------------------------------------------
+*
+* This utility is primarily intended for logging and debugging purposes,
+* especially in CLI tools or build pipelines where distinguishing between
+* default and user-provided values is important.
+*
+* The comparison is performed using `Object.is` to ensure accurate detection,
+* including edge cases such as:
+* - `NaN` vs `NaN`.
+* - `-0` vs `+0`.
+*
+* @template T - The type of the option value being compared.
+*
+* @param {unknown} value - The actual value used at runtime.
+* @param {unknown} defaultValue - The default value defined by the tool.
+*
+* @returns
+* A string indicating the source of the value:
+*
+* - `"default"` when `value` is strictly equal to `defaultValue`.
+* - `"overridden"` when the value differs from the default.
+*
+* @example
+* ```ts
+* sourceOf("dist", "dist"); // ➔ "default"
+* sourceOf("dist/types", "dist"); // ➔ "overridden"
+* ```
+*
+* @example
+* ***CLI-style option logging:***
+* ```ts
+* BUILD_LOGGER.OPTIONS(
+*   "outDir",
+*   outDir,
+*   sourceOf(outDir, DEFAULTS.outDir)
+* );
+* ```
+*/
+declare const sourceOf: <T>(value: T, defaultValue: T) => "default" | "overridden";
+/** ----------------------------------------------------------------
+* * ***Deep default source detector.***
+* ----------------------------------------------------------------
+*
+* Determines whether a given value is structurally identical
+* to its default value using deep comparison.
+*
+* Unlike `Object.is`, this utility compares object contents
+* recursively rather than checking reference identity.
+*
+* Intended for configuration systems where option objects
+* may be cloned or reconstructed but still represent the
+* default state.
+*
+* @template T - Value type being compared.
+*
+* @param value - Current runtime value.
+* @param defaultValue - Default reference value.
+*
+* @returns
+* - `"default"` ➔ If values are deeply equal.
+* - `"overridden"` ➔ If values differ.
+*
+* @example
+* ```ts
+* sourceOfIsDeepStrictEqual(
+*   { onlyFiles: true },
+*   { onlyFiles: true }
+* );
+* // "default"
+* ```
+*/
+declare const sourceOfIsDeepStrictEqual: <T>(value: T, defaultValue: T) => "default" | "overridden";
+/** -------------------------------------------------------------------
+* * ***Structured build-time console logger with consistent formatting,
+* icons, and colorized output.***
+* --------------------------------------------------------------------
+*
+* `BUILD_LOGGER` provides a collection of standardized logging helpers
+* intended for **CLI tools, build scripts, and Node.js-based workflows**.
+*
+* - **It ensures:**
+*      - Consistent log structure across different build phases.
+*      - Clear visual distinction between states (start, success, skip, error).
+*      - Emoji or ASCII icon support depending on environment configuration.
+*      - Readable, colorized output via `picocolors`.
+*
+* Emoji usage is controlled via the environment variable:
+*
+* ```
+* FORCE_EMOJI=1
+* ```
+*
+* When disabled, all icons gracefully fall back to ASCII-safe symbols.
+*
+* ---
+*
+* - **Behavior:**
+*      - Uses emoji icons when `FORCE_EMOJI === "1"`.
+*      - Falls back to ASCII symbols otherwise.
+*      - Applies consistent spacing, bulleting, and indentation.
+*      - Formats messages using `picocolors` for visibility.
+*      - Safely extracts error messages from unknown error values.
+*
+* ---
+*
+* - **Available log actions:**
+*      - `SOURCE_OF`:
+*         - See {@link sourceOf | **`sourceOf`**} helpers.
+*
+*      - `OPTIONS({ label, value, source, isRequired })`:
+*         - Logs the options argument function using
+*        {@link sourceOf | **`sourceOf`**} helper.
+*
+*      - `NEW_LINE()`:
+*         - *Inserts an empty line in the console output.*
+*
+*      - `ON_STARTING({ actionName })`:
+*         - *Logs the start of a build or processing action.*
+*
+*      - `ON_FINISH({ actionName, count })`:
+*         - *Logs successful completion with item count.*
+*
+*      - `ON_SKIPPING({ actionName, reasonEndText })`:
+*         - *Logs skipped actions with human-readable reasons.*
+*
+*      - `ON_ERROR({ actionName, error })`:
+*         - *Logs formatted error output with extracted message.*
+*
+*      - `ON_PROCESS_COPY({ actionName, copyFrom, copyTo })`:
+*         - *Logs file copy operations.*
+*
+*      - `ON_PROCESS({ actionName, nameDirect })`:
+*         - *Logs generic processing steps.*
+*
+*      - `ON_PROCESS_REFERENCING({ actionName, referenceFrom, referenceTo })`:
+*         - *Logs reference or linking operations.*
+*
+* ---
+*
+* This logger is intentionally **side-effectful** and writes directly
+* to `console.log` / `console.error`.
+*
+* It is designed for **human-readable output**, not structured logging
+* or machine parsing.
+*/
+declare const BUILD_LOGGER: LoggerBuilder;
+type LoggerBuilder = {
+  SOURCE_OF: typeof sourceOf;
+  OPTIONS(label: string, value: unknown, source: ReturnType<typeof sourceOf> | AnyString, isRequired?: boolean): void;
+  SECTION(title: string, options?: LoggerBuilderSection): void;
+  NEW_LINE(value?: string): void;
+  ON_STARTING: (options: LoggerBuilderOnStarting) => void;
+  ON_FINISH: (options: LoggerBuilderOnFinish) => void;
+  ON_SKIPPING: (options: LoggerBuilderOnSkipping) => void;
+  ON_ERROR: (options: LoggerBuilderOnError) => void;
+  ON_PROCESS: (options: LoggerBuilderOnProcess) => void;
+  ON_PROCESS_COPY: (options: LoggerBuilderOnProcessCopy) => void;
+  ON_PROCESS_COPY_ERROR: (options: LoggerBuilderOnProcessCopyError) => void;
+  ON_PROCESS_REFERENCING: (options: LoggerBuilderOnProcessReferencing) => void;
+};
+type LoggerBuilderSection = {
+  /**
+  * @default ICON.config
+  */
+  icon?: string;
+  /**
+  * @default ""
+  */
+  indent?: string;
+};
+type LoggerBuilderOnStarting = {
+  /** The name of the action being started.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** Connector word used before the action name.
+  *
+  * @default
+  * "to"
+  */
+  textDirectAction?: string;
+};
+type LoggerBuilderOnFinish = {
+  /** The name of the completed action.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** The success text.
+  *
+  * @default
+  * @default "Success"
+  */
+  textSuccess?: string;
+  /** Label for the count unit.
+  *
+  * @default
+  * "file"
+  */
+  typeCount?: string;
+  /** Number of processed items.
+  *
+  * @default
+  * undefined
+  */
+  count: number;
+  /** Progress of processed items (e.g. `2/7`).
+  *
+  * Represents how many items have been processed relative to the total.
+  *
+  * @example
+  * "2/7"
+  */
+  progress?: string;
+};
+type LoggerBuilderOnSkipping = {
+  /** The name of the skipped action.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** Connector word explaining the reason.
+  *
+  * @default
+  * "because"
+  */
+  reasonTitle?: string;
+  /** Short reason phrase.
+  *
+  * @default
+  * "nothing left"
+  */
+  reasonSkipAction?: string;
+  /** Contextual explanation for the skip.
+  *
+  * @default
+  * undefined
+  */
+  reasonEndText: string;
+  /** Type of resource involved.
+  *
+  * @default
+  * "files"
+  */
+  reasonType?: string;
+  /** Connector word before the target.
+  *
+  * @default
+  * "to"
+  */
+  textDirectAction?: string;
+};
+type LoggerBuilderOnError = {
+  /** The name of the action that failed.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** Connector word before the action name.
+  *
+  * @default
+  * "to"
+  */
+  textDirectAction?: string;
+  /** Unknown error object or `Error` instance.
+  *
+  */
+  error: unknown;
+};
+type LoggerBuilderOnProcess = {
+  /** Description of the process.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** Sequence number.
+  *
+  * @default
+  * undefined
+  */
+  count: number;
+  /** Connector word before the target.
+  *
+  * @default
+  * "in"
+  */
+  textDirectFolder?: string;
+  /** Target name or location.
+  *
+  * @default
+  * undefined
+  */
+  nameDirect: string;
+};
+type LoggerBuilderOnProcessCopy = {
+  /** The name of the action being the copy action.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** Sequence number of the process.
+  *
+  * @default
+  * undefined
+  */
+  count: number;
+  /** Connector text before source path.
+  *
+  * @default
+  * "from"
+  */
+  textFrom?: string;
+  /** Source path.
+  *
+  * @default
+  * undefined
+  */
+  copyFrom: string;
+  /** Destination path.
+  *
+  * @default
+  * undefined
+  */
+  copyTo: string;
+  /** Arrow symbol between paths.
+  *
+  * @default
+  * "➔"
+  */
+  textArrow?: string;
+};
+type LoggerBuilderOnProcessCopyError = {
+  /** The name of the action being the error copy action.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** Sequence number of the process.
+  *
+  * @default
+  * undefined
+  */
+  count: number;
+  /** Index number parameter.
+  *
+  * @default
+  * undefined
+  */
+  index?: number;
+  /** Index key name for parameter.
+  *
+  * @default
+  * undefined
+  */
+  indexKey?: string;
+  /** Connector text before source path.
+  *
+  * @default
+  * "from"
+  */
+  textFrom?: string;
+  /** Source path.
+  *
+  * @default
+  * undefined
+  */
+  copyFrom: string;
+  /** The reason error on copying.
+  *
+  * @default
+  * undefined
+  */
+  errorReason: string | Error;
+  /** Connector word explaining the reason.
+  *
+  * @default
+  * "because"
+  */
+  textReason?: string;
+};
+type LoggerBuilderOnProcessReferencing = {
+  /** The name of the action being the referencing action.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** Sequence number.
+  *
+  * @default
+  * undefined
+  */
+  count: number;
+  /** Connector text before source.
+  *
+  * @default
+  * "from"
+  */
+  textFrom?: string;
+  /** Source reference path.
+  *
+  * @default
+  * undefined
+  */
+  referenceFrom: string;
+  /** Target reference path.
+  *
+  * @default
+  * undefined
+  */
+  referenceTo: string;
+  /** Arrow symbol between references.
+  *
+  * @default
+  * "➔"
+  */
+  textArrow?: string;
+};
 /** ----------------------------------------------------------------
 * * ***Node.js–only filesystem utilities (fs-extra).***
 * ----------------------------------------------------------------
@@ -120,5 +550,5 @@ declare const fsExtra: typeof _fsExtra;
 * @environment node
 */
 declare const fastGlob: typeof _fastGlob;
-export { ICONS, type PatternConfig, type PatternOptions, defaultPatternOptions, fastGlob, fsExtra };
+export { BUILD_LOGGER, ICONS, type PatternConfig, type PatternOptions, defaultPatternOptions, fastGlob, fsExtra, sourceOf, sourceOfIsDeepStrictEqual };
 //# sourceMappingURL=server.d.ts.map

package/dist/utils/server.js

@@ -2,11 +2,11 @@
 * ========================================================================
 *  @rzl-zone/build-tools
 * ------------------------------------------------------------------------
-*  Version: `0.0.10`
+*  Version: `0.0.12-beta.0`
 *  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/build-tools`
 * ========================================================================
 */
 
-import { i as defaultPatternOptions, n as fsExtra, r as ICONS, t as fastGlob } from "../server-BA7ruG1h.js";
-export { ICONS, defaultPatternOptions, fastGlob, fsExtra };
+import { a as sourceOfIsDeepStrictEqual, i as sourceOf, n as fsExtra, o as ICONS, r as BUILD_LOGGER, s as defaultPatternOptions, t as fastGlob } from "../server-Owi9-DW1.js";
+export { BUILD_LOGGER, ICONS, defaultPatternOptions, fastGlob, fsExtra, sourceOf, sourceOfIsDeepStrictEqual };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rzl-zone/build-tools",
-  "version": "0.0.10",
+  "version": "0.0.12-beta.0",
   "description": "Toolkit to standardize and improve TypeScript and JavaScript build outputs.",
   "license": "MIT",
   "author": "Rizalvin Dwiky <rizalvindwiky1998@gmail.com>",
@@ -44,6 +44,7 @@
     "dist",
     "README.md",
     "LICENSE.md",
+    "LICENSE",
     "!**/*.test.*"
   ],
   "exports": {
@@ -117,19 +118,22 @@
     "fs-extra": "^11.3.4",
     "picocolors": "^1.1.1",
     "semver": "^7.7.4",
-    "@rzl-zone/node-only": "0.0.9"
+    "shell-quote": "^1.8.3",
+    "@rzl-zone/node-only": "0.0.10-beta.0"
   },
   "devDependencies": {
     "@types/babel__traverse": "^7.28.0",
     "@types/fs-extra": "^11.0.4",
+    "@types/shell-quote": "^1.7.5",
     "eslint": "^9.39.2",
     "rolldown": "^1.0.0-rc.15",
     "terser": "^5.46.1",
-    "tsdown": "0.21.8",
+    "tsdown": "0.22.0",
     "type-fest": "5.5.0",
-    "typescript": "^6.0.2",
-    "@workspace/eslint-config": "0.0.0",
-    "@workspace/typescript-config": "0.0.0"
+    "typescript": "6.0.3",
+    "unrun": "^0.3.0",
+    "@workspace/typescript-config": "0.0.0",
+    "@workspace/eslint-config": "0.0.0"
   },
   "peerDependencies": {
     "rolldown": ">=1",

package/dist/client-BmfdVI22.js

@@ -1,160 +0,0 @@
-/*!
-* ========================================================================
-*  @rzl-zone/build-tools
-* ------------------------------------------------------------------------
-*  Version: `0.0.10`
-*  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
-*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/build-tools`
-* ========================================================================
-*/
-
-import { c as isNil, d as isNumber, f as isObject, g as isString, h as isSet, i as isBoolean, l as isNonEmptyString, m as isRegExp, o as isFunction, p as isPlainObject, r as isArray, s as isMap, t as deepFreeze } from "./helper-CWU8QYq3.js";
-import pcr from "picocolors";
-const hasGlobalRequire = (value) => isObject(value) && isFunction(value.require);
-const getRuntimeRequire = () => {
-	if (!hasGlobalRequire(globalThis)) return void 0;
-	return globalThis.require;
-};
-const __runtimeRequire = ((x) => {
-	const r = getRuntimeRequire();
-	if (r) return r;
-	if (typeof Proxy !== "undefined") return new Proxy(x, { get(target, prop) {
-		const r2 = getRuntimeRequire();
-		return r2 ? r2[prop] : target[prop];
-	} });
-	return x;
-})(function(id) {
-	const r = getRuntimeRequire();
-	if (r) return r.call(this, id);
-	throw new Error(`Calling \`require\` for "${id}" in an environment that doesn't expose the \`require\` function.`);
-});
-const picocolors = pcr;
-const NEWLINE = atob("Cg==");
-const EOL = hasGlobalRequire(globalThis) ? __runtimeRequire("node:os").EOL : NEWLINE;
-function plural(count, word, pluralWord) {
-	if (count === 1) return word;
-	return pluralWord ?? `${word}s`;
-}
-function padText(value, options = {}) {
-	const { start = true, end = true, padOnInvalid = true } = options;
-	if (!isNonEmptyString(value)) return padOnInvalid ? " " : "";
-	return `${start ? " " : ""}${value}${end ? " " : ""}`;
-}
-function joinInline(...text) {
-	return text.filter(Boolean).join(" ");
-}
-function joinLines(...text) {
-	return text.filter(Boolean).join(EOL);
-}
-function joinLinesLoose(...text) {
-	return text.filter((v) => v !== false && v !== null && v !== void 0).join(EOL);
-}
-function formatOptionValue(value, options) {
-	const { pretty = false, indent = 2, sortKeys = false, sortArray = false } = options ?? {};
-	const indentUnit = " ".repeat(indent);
-	function formatRecursive(input, depth = 0) {
-		const currentIndent = indentUnit.repeat(depth);
-		const nextIndent = indentUnit.repeat(depth + 1);
-		const joinInline = picocolors.dim(", ");
-		const joinPretty = `,${EOL}`;
-		if (isSet(input)) return formatRecursive([...input], depth);
-		if (isMap(input)) return formatRecursive(Object.fromEntries(input), depth);
-		if (isArray(input)) {
-			const arr = sortArray ? [...input].sort() : input;
-			if (arr.length === 0) return picocolors.gray("[]");
-			if (!pretty) {
-				const items = arr.map((v) => formatRecursive(v, depth)).join(joinInline);
-				return picocolors.gray("[") + items + picocolors.gray("]");
-			}
-			const items = arr.map((v) => nextIndent + formatRecursive(v, depth + 1)).join(joinPretty);
-			return picocolors.gray(`[${EOL}`) + items + EOL + currentIndent + picocolors.gray("]");
-		}
-		if (isPlainObject(input)) {
-			let entries = Object.entries(input);
-			if (sortKeys) entries = entries.sort(([a], [b]) => a.localeCompare(b));
-			if (entries.length === 0) return picocolors.gray("{}");
-			if (!pretty) {
-				const props = entries.map(([key, val]) => {
-					return picocolors.dim(key) + picocolors.gray(": ") + formatRecursive(val, depth);
-				}).join(joinInline);
-				return picocolors.gray("{ ") + props + picocolors.gray(" }");
-			}
-			const props = entries.map(([key, val]) => {
-				return nextIndent + picocolors.dim(key) + picocolors.gray(": ") + formatRecursive(val, depth + 1);
-			}).join(joinPretty);
-			return picocolors.gray(`{${EOL}`) + props + EOL + currentIndent + picocolors.gray("}");
-		}
-		if (isRegExp(input)) return picocolors.greenBright("/") + picocolors.redBright(input.source) + picocolors.greenBright("/") + picocolors.magentaBright(input.flags);
-		if (isString(input)) return picocolors.gray(`"${input}"`);
-		if (isNumber(input, { includeNaN: true })) return picocolors.redBright(String(input));
-		if (isBoolean(input)) return picocolors.redBright(String(input));
-		if (isNil(input)) return picocolors.redBright(String(input));
-		if (isObject(input)) return picocolors.cyanBright(Object.prototype.toString.call(input));
-		return picocolors.cyanBright(String(input));
-	}
-	return formatRecursive(value);
-}
-var ConfigurationError = class ConfigurationError extends Error {
-	static _LABEL = "Invalid configuration";
-	static _normalizeReason(reason) {
-		const trimmed = reason.trim().replace(/\.*$/, "");
-		if (trimmed.length === 0) return trimmed;
-		return trimmed.charAt(0).toLowerCase() + trimmed.slice(1);
-	}
-	static _compose(field, body, context) {
-		const prefix = context ? `${ConfigurationError._LABEL} in ${ConfigurationError.wrapCode(context)}:` : `${ConfigurationError._LABEL}:`;
-		return ConfigurationError.format(`${prefix} ${ConfigurationError.wrapCode(field)} ${body}`);
-	}
-	constructor(message, details) {
-		super(message);
-		this.name = ConfigurationError.NAME;
-		this.code = ConfigurationError.CODE;
-		this.details = details ? deepFreeze({ ...details }) : void 0;
-		Object.setPrototypeOf(this, new.target.prototype);
-		if (Error.captureStackTrace) Error.captureStackTrace(this, ConfigurationError);
-		if (Object.getPrototypeOf(this) === ConfigurationError.prototype) Object.freeze(this);
-	}
-	static NAME = "ConfigurationError";
-	static CODE = "CONFIGURATION_ERROR";
-	code = ConfigurationError.CODE;
-	details;
-	static format(message) {
-		if (typeof message !== "string" || message.trim().length === 0) throw new TypeError(`${this._LABEL}: ${ConfigurationError.NAME}.format(message) expects a non-empty string.`);
-		return message.trim().replace(/\.*$/, "") + ".";
-	}
-	static wrapCode(value) {
-		if (!isNonEmptyString(value)) throw new TypeError(`${this._LABEL}: ${ConfigurationError.NAME}.wrapCode(value) expects a non-empty string.`);
-		return `\`${value.replace(/`+/g, "").trim()}\``;
-	}
-	static is(value) {
-		if (typeof value !== "object" || value === null) return false;
-		if (!("code" in value) || !("name" in value)) return false;
-		const { code, name } = value;
-		return code === ConfigurationError.CODE && name === ConfigurationError.NAME;
-	}
-	toJSON() {
-		return {
-			name: this.name,
-			message: this.message,
-			code: this.code,
-			details: this.details,
-			stack: this.stack
-		};
-	}
-	static invalid(field, reason, details, context) {
-		const body = ConfigurationError._normalizeReason(reason);
-		return new ConfigurationError(ConfigurationError._compose(field, body, context), {
-			...details,
-			...context ? { context } : {}
-		});
-	}
-	static type(field, expected, received, context) {
-		const body = `must be ${expected}`;
-		return new ConfigurationError(ConfigurationError._compose(field, body, context), {
-			received,
-			...context ? { context } : {}
-		});
-	}
-};
-export { joinInline as a, padText as c, formatOptionValue as i, picocolors as l, EOL as n, joinLines as o, NEWLINE as r, joinLinesLoose as s, ConfigurationError as t, plural as u };
-//# sourceMappingURL=client-BmfdVI22.js.map