@socketsecurity/lib 3.2.7 → 3.3.0

package/dist/logger.d.ts

@@ -13,6 +13,7 @@
  * console.log(`${LOG_SYMBOLS.warn} Warning message`)
  * console.log(`${LOG_SYMBOLS.info} Information message`)
  * console.log(`${LOG_SYMBOLS.step} Processing step`)
+ * console.log(`${LOG_SYMBOLS.reason} Working through logic`)
  * ```
  */
 type LogSymbols = {
@@ -20,6 +21,8 @@ type LogSymbols = {
     fail: string;
     /** Blue colored information symbol (ℹ or i in ASCII) */
     info: string;
+    /** Dimmed yellow reasoning/working symbol (∴ or :. in ASCII) */
+    reason: string;
     /** Cyan colored step symbol (→ or > in ASCII) */
     step: string;
     /** Green colored success symbol (✔ or √ in ASCII) */
@@ -62,9 +65,9 @@ export type { LogSymbols, LoggerMethods, Task };
 /**
  * Log symbols for terminal output with colored indicators.
  *
- * Provides colored Unicode symbols (✔, ✖, ⚠, ℹ, →) with ASCII fallbacks (√, ×, ‼, i, >)
+ * Provides colored Unicode symbols (✖, ℹ, ∴, →, ✔, ⚠) with ASCII fallbacks (×, i, :., >, √, ‼)
  * for terminals that don't support Unicode. Symbols are colored according to the active
- * theme's color palette (success, error, warning, info, step).
+ * theme's color palette (error, info, reason, step, success, warning).
  *
  * The symbols are lazily initialized on first access and automatically update when the
  * fallback theme changes (via setTheme()). Note that LOG_SYMBOLS reflect the global
@@ -74,11 +77,12 @@ export type { LogSymbols, LoggerMethods, Task };
  * ```typescript
  * import { LOG_SYMBOLS } from '@socketsecurity/lib'
  *
- * console.log(`${LOG_SYMBOLS.success} Build completed`)    // Theme success color ✔
  * console.log(`${LOG_SYMBOLS.fail} Build failed`)          // Theme error color ✖
- * console.log(`${LOG_SYMBOLS.warn} Deprecated API used`)   // Theme warning color ⚠
  * console.log(`${LOG_SYMBOLS.info} Starting process`)      // Theme info color ℹ
+ * console.log(`${LOG_SYMBOLS.reason} Analyzing dependencies`) // Dimmed yellow ∴
  * console.log(`${LOG_SYMBOLS.step} Processing files`)      // Theme step color →
+ * console.log(`${LOG_SYMBOLS.success} Build completed`)    // Theme success color ✔
+ * console.log(`${LOG_SYMBOLS.warn} Deprecated API used`)   // Theme warning color ⚠
  * ```
  */
 export declare const LOG_SYMBOLS: Record<string, string>;
@@ -288,6 +292,35 @@ export declare class Logger {
      * ```
      */
     assert(value: unknown, ...message: unknown[]): this;
+    /**
+     * Clears the current line in the terminal.
+     *
+     * Moves the cursor to the beginning of the line and clears all content.
+     * Works in both TTY and non-TTY environments. Useful for clearing
+     * progress indicators created with `progress()`.
+     *
+     * The stream to clear (stderr or stdout) depends on whether the logger
+     * is stream-bound.
+     *
+     * @returns The logger instance for chaining
+     *
+     * @example
+     * ```typescript
+     * logger.progress('Loading...')
+     * // ... do work ...
+     * logger.clearLine()
+     * logger.success('Loaded')
+     *
+     * // Clear multiple progress updates
+     * for (const file of files) {
+     *   logger.progress(`Processing ${file}`)
+     *   processFile(file)
+     *   logger.clearLine()
+     * }
+     * logger.success('All files processed')
+     * ```
+     */
+    clearLine(): this;
     /**
      * Clears the visible terminal screen.
      *
@@ -413,6 +446,28 @@ export declare class Logger {
      * ```
      */
     dirxml(...data: unknown[]): this;
+    /**
+     * Logs a completion message with a success symbol (alias for `success()`).
+     *
+     * Provides semantic clarity when marking something as "done". Does NOT
+     * automatically clear the current line - call `clearLine()` first if
+     * needed after using `progress()`.
+     *
+     * @param args - Message and additional arguments to log
+     * @returns The logger instance for chaining
+     *
+     * @example
+     * ```typescript
+     * logger.done('Task completed')
+     *
+     * // After progress indicator
+     * logger.progress('Processing...')
+     * // ... do work ...
+     * logger.clearLine()
+     * logger.done('Processing complete')
+     * ```
+     */
+    done(...args: unknown[]): this;
     /**
      * Logs an error message to stderr.
      *
@@ -614,6 +669,53 @@ export declare class Logger {
      * ```
      */
     logNewline(): this;
+    /**
+     * Shows a progress indicator that can be cleared with `clearLine()`.
+     *
+     * Displays a simple status message with a '∴' prefix. Does not include
+     * animation or spinner. Intended to be cleared once the operation completes.
+     * The output stream (stderr or stdout) depends on whether the logger is
+     * stream-bound.
+     *
+     * @param text - The progress message to display
+     * @returns The logger instance for chaining
+     *
+     * @example
+     * ```typescript
+     * logger.progress('Processing files...')
+     * // ... do work ...
+     * logger.clearLine()
+     * logger.success('Files processed')
+     *
+     * // Stream-specific progress
+     * logger.stdout.progress('Loading...')
+     * // ... do work ...
+     * logger.stdout.clearLine()
+     * logger.stdout.log('Done')
+     * ```
+     */
+    progress(text: string): this;
+    /**
+     * Logs a reasoning/working message with a dimmed yellow therefore symbol.
+     *
+     * Automatically prefixes the message with `LOG_SYMBOLS.reason` (dimmed yellow ∴).
+     * Useful for showing intermediate reasoning, logic steps, or "working" output
+     * that leads to a conclusion. Always outputs to stderr. If the message starts
+     * with an existing symbol, it will be stripped and replaced.
+     *
+     * @param args - Message and additional arguments to log
+     * @returns The logger instance for chaining
+     *
+     * @example
+     * ```typescript
+     * logger.step('Analyzing package security')
+     * logger.reason('Found 3 direct dependencies')
+     * logger.reason('Checking 47 transitive dependencies')
+     * logger.reason('Risk score: 8.5/10')
+     * logger.fail('Package blocked due to high risk')
+     * ```
+     */
+    reason(...args: unknown[]): this;
     /**
      * Resets all indentation to zero.
      *
@@ -706,28 +808,6 @@ export declare class Logger {
      * ```
      */
     success(...args: unknown[]): this;
-    /**
-     * Logs a completion message with a success symbol (alias for `success()`).
-     *
-     * Provides semantic clarity when marking something as "done". Does NOT
-     * automatically clear the current line - call `clearLine()` first if
-     * needed after using `progress()`.
-     *
-     * @param args - Message and additional arguments to log
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.done('Task completed')
-     *
-     * // After progress indicator
-     * logger.progress('Processing...')
-     * // ... do work ...
-     * logger.clearLine()
-     * logger.done('Processing complete')
-     * ```
-     */
-    done(...args: unknown[]): this;
     /**
      * Displays data in a table format.
      *
@@ -893,61 +973,6 @@ export declare class Logger {
      * ```
      */
     write(text: string): this;
-    /**
-     * Shows a progress indicator that can be cleared with `clearLine()`.
-     *
-     * Displays a simple status message with a '∴' prefix. Does not include
-     * animation or spinner. Intended to be cleared once the operation completes.
-     * The output stream (stderr or stdout) depends on whether the logger is
-     * stream-bound.
-     *
-     * @param text - The progress message to display
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.progress('Processing files...')
-     * // ... do work ...
-     * logger.clearLine()
-     * logger.success('Files processed')
-     *
-     * // Stream-specific progress
-     * logger.stdout.progress('Loading...')
-     * // ... do work ...
-     * logger.stdout.clearLine()
-     * logger.stdout.log('Done')
-     * ```
-     */
-    progress(text: string): this;
-    /**
-     * Clears the current line in the terminal.
-     *
-     * Moves the cursor to the beginning of the line and clears all content.
-     * Works in both TTY and non-TTY environments. Useful for clearing
-     * progress indicators created with `progress()`.
-     *
-     * The stream to clear (stderr or stdout) depends on whether the logger
-     * is stream-bound.
-     *
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.progress('Loading...')
-     * // ... do work ...
-     * logger.clearLine()
-     * logger.success('Loaded')
-     *
-     * // Clear multiple progress updates
-     * for (const file of files) {
-     *   logger.progress(`Processing ${file}`)
-     *   processFile(file)
-     *   logger.clearLine()
-     * }
-     * logger.success('All files processed')
-     * ```
-     */
-    clearLine(): this;
 }
 /**
  * Get the default logger instance.