@socketsecurity/lib 1.0.5 → 1.1.1

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.1] - 2025-10-23
+
+### Fixed
+
+- Fixed shimmer text effects not respecting CI environment detection (now disabled in CI to prevent ANSI escape codes in logs)
+
+## [1.1.0] - 2025-10-23
+
+### Added
+
+- Added `filterOutput` option to `stdio/mask` for filtering output chunks before display/buffering
+- Added `overrideExitCode` option to `stdio/mask` for customizing exit codes based on captured output
+- Added comprehensive JSDoc documentation across entire library for enhanced VSCode IntelliSense
+  - Detailed @param, @returns, @template, @throws tags
+  - Practical @example blocks with real-world usage patterns
+  - @default tags showing default values
+  - Enhanced interface property documentation
+
+### Changed
+
+- Improved TypeScript type hints and tooltips throughout library
+- Enhanced documentation for all core utilities (arrays, fs, git, github, http-request, json, logger, objects, path, promises, spawn, spinner, strings)
+- Enhanced documentation for stdio utilities (clear, divider, footer, header, mask, progress, prompts, stderr, stdout)
+- Enhanced documentation for validation utilities (json-parser, types)
+
 ## [1.0.5] - 2025-10-22
 
 ### Added

package/dist/arrays.d.ts

@@ -1,10 +1,63 @@
 /**
  * Split an array into chunks of a specified size.
+ *
+ * Divides an array into smaller arrays of the specified chunk size.
+ * The last chunk may contain fewer elements if the array length is not
+ * evenly divisible by the chunk size.
+ *
+ * @param arr - The array to split into chunks (can be readonly)
+ * @param size - Size of each chunk. Must be greater than 0.
+ * @default 2
+ * @returns Array of chunks, where each chunk is an array of elements
+ * @throws {Error} If chunk size is less than or equal to 0
+ *
+ * @example
+ * ```ts
+ * // Split into pairs (default)
+ * arrayChunk([1, 2, 3, 4, 5])
+ * // Returns: [[1, 2], [3, 4], [5]]
+ *
+ * // Split into groups of 3
+ * arrayChunk(['a', 'b', 'c', 'd', 'e', 'f', 'g'], 3)
+ * // Returns: [['a', 'b', 'c'], ['d', 'e', 'f'], ['g']]
+ *
+ * // Works with readonly arrays
+ * const readonlyArr = [1, 2, 3] as const
+ * arrayChunk(readonlyArr)
+ * // Returns: [[1, 2], [3]]
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function arrayChunk<T>(arr: T[] | readonly T[], size?: number | undefined): T[][];
 /**
  * Get unique values from an array.
+ *
+ * Returns a new array containing only the unique values from the input array.
+ * Uses `Set` internally for efficient deduplication. Order of first occurrence
+ * is preserved.
+ *
+ * @param arr - The array to deduplicate (can be readonly)
+ * @returns New array with duplicate values removed
+ *
+ * @example
+ * ```ts
+ * // Remove duplicate numbers
+ * arrayUnique([1, 2, 2, 3, 1, 4])
+ * // Returns: [1, 2, 3, 4]
+ *
+ * // Remove duplicate strings
+ * arrayUnique(['apple', 'banana', 'apple', 'cherry'])
+ * // Returns: ['apple', 'banana', 'cherry']
+ *
+ * // Works with readonly arrays
+ * const readonlyArr = [1, 1, 2] as const
+ * arrayUnique(readonlyArr)
+ * // Returns: [1, 2]
+ *
+ * // Empty arrays return empty
+ * arrayUnique([])
+ * // Returns: []
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function arrayUnique<T>(arr: T[] | readonly T[]): T[];
@@ -15,15 +68,105 @@ export declare function arrayUnique<T>(arr: T[] | readonly T[]): T[];
 /**
  * Alias for native Array.isArray.
  * Determines whether the passed value is an array.
+ *
+ * This is a direct reference to the native `Array.isArray` method,
+ * providing a type guard that narrows the type to an array type.
+ * Exported for consistency with other array utilities in this module.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is an array, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * // Check if value is an array
+ * isArray([1, 2, 3])
+ * // Returns: true
+ *
+ * isArray('not an array')
+ * // Returns: false
+ *
+ * isArray(null)
+ * // Returns: false
+ *
+ * // Type guard usage
+ * function processValue(value: unknown) {
+ *   if (isArray(value)) {
+ *     // TypeScript knows value is an array here
+ *     console.log(value.length)
+ *   }
+ * }
+ * ```
  */
 export declare const isArray: (arg: any) => arg is any[];
 /**
  * Join array elements with proper "and" conjunction formatting.
+ *
+ * Formats an array of strings into a grammatically correct list using
+ * "and" as the conjunction. Uses `Intl.ListFormat` for proper English
+ * formatting with Oxford comma support.
+ *
+ * @param arr - Array of strings to join (can be readonly)
+ * @returns Formatted string with proper "and" conjunction
+ *
+ * @example
+ * ```ts
+ * // Two items
+ * joinAnd(['apples', 'oranges'])
+ * // Returns: "apples and oranges"
+ *
+ * // Three or more items (Oxford comma)
+ * joinAnd(['apples', 'oranges', 'bananas'])
+ * // Returns: "apples, oranges, and bananas"
+ *
+ * // Single item
+ * joinAnd(['apples'])
+ * // Returns: "apples"
+ *
+ * // Empty array
+ * joinAnd([])
+ * // Returns: ""
+ *
+ * // Usage in messages
+ * const items = ['React', 'Vue', 'Angular']
+ * console.log(`You can choose ${joinAnd(items)}`)
+ * // Outputs: "You can choose React, Vue, and Angular"
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function joinAnd(arr: string[] | readonly string[]): string;
 /**
  * Join array elements with proper "or" disjunction formatting.
+ *
+ * Formats an array of strings into a grammatically correct list using
+ * "or" as the disjunction. Uses `Intl.ListFormat` for proper English
+ * formatting with Oxford comma support.
+ *
+ * @param arr - Array of strings to join (can be readonly)
+ * @returns Formatted string with proper "or" disjunction
+ *
+ * @example
+ * ```ts
+ * // Two items
+ * joinOr(['yes', 'no'])
+ * // Returns: "yes or no"
+ *
+ * // Three or more items (Oxford comma)
+ * joinOr(['red', 'green', 'blue'])
+ * // Returns: "red, green, or blue"
+ *
+ * // Single item
+ * joinOr(['maybe'])
+ * // Returns: "maybe"
+ *
+ * // Empty array
+ * joinOr([])
+ * // Returns: ""
+ *
+ * // Usage in prompts
+ * const options = ['npm', 'yarn', 'pnpm']
+ * console.log(`Choose a package manager: ${joinOr(options)}`)
+ * // Outputs: "Choose a package manager: npm, yarn, or pnpm"
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function joinOr(arr: string[] | readonly string[]): string;

package/dist/arrays.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/arrays.ts"],
-  "sourcesContent": ["/**\n * @fileoverview Array utility functions for formatting lists and collections.\n * Provides conjunction and disjunction formatters using Intl.ListFormat.\n */\n\nlet _conjunctionFormatter: Intl.ListFormat | undefined\n/**\n * Get a cached Intl.ListFormat instance for conjunction (and) formatting.\n * @private\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getConjunctionFormatter() {\n  if (_conjunctionFormatter === undefined) {\n    _conjunctionFormatter = new Intl.ListFormat('en', {\n      style: 'long',\n      // \"and\" lists.\n      type: 'conjunction',\n    })\n  }\n  return _conjunctionFormatter\n}\n\nlet _disjunctionFormatter: Intl.ListFormat | undefined\n/**\n * Get a cached Intl.ListFormat instance for disjunction (or) formatting.\n * @private\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getDisjunctionFormatter() {\n  if (_disjunctionFormatter === undefined) {\n    _disjunctionFormatter = new Intl.ListFormat('en', {\n      style: 'long',\n      // \"or\" lists.\n      type: 'disjunction',\n    })\n  }\n  return _disjunctionFormatter\n}\n\n/**\n * Split an array into chunks of a specified size.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function arrayChunk<T>(\n  arr: T[] | readonly T[],\n  size?: number | undefined,\n): T[][] {\n  const chunkSize = size ?? 2\n  if (chunkSize <= 0) {\n    throw new Error('Chunk size must be greater than 0')\n  }\n  const { length } = arr\n  const actualChunkSize = Math.min(length, chunkSize)\n  const chunks = []\n  for (let i = 0; i < length; i += actualChunkSize) {\n    chunks.push(arr.slice(i, i + actualChunkSize) as T[])\n  }\n  return chunks\n}\n\n/**\n * Get unique values from an array.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function arrayUnique<T>(arr: T[] | readonly T[]): T[] {\n  return [...new Set(arr)]\n}\n\n// IMPORTANT: Do not use destructuring here - use direct assignment instead.\n// tsgo has a bug that incorrectly transpiles destructured exports, resulting in\n// `exports.SomeName = void 0;` which causes runtime errors.\n// See: https://github.com/SocketDev/socket-packageurl-js/issues/3\n\n/**\n * Alias for native Array.isArray.\n * Determines whether the passed value is an array.\n */\nexport const isArray = Array.isArray\n\n/**\n * Join array elements with proper \"and\" conjunction formatting.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function joinAnd(arr: string[] | readonly string[]): string {\n  return getConjunctionFormatter().format(arr)\n}\n\n/**\n * Join array elements with proper \"or\" disjunction formatting.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function joinOr(arr: string[] | readonly string[]): string {\n  return getDisjunctionFormatter().format(arr)\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,IAAI;AAAA;AAMJ,SAAS,0BAA0B;AACjC,MAAI,0BAA0B,QAAW;AACvC,4BAAwB,IAAI,KAAK,WAAW,MAAM;AAAA,MAChD,OAAO;AAAA;AAAA,MAEP,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AACA,SAAO;AACT;AAEA,IAAI;AAAA;AAMJ,SAAS,0BAA0B;AACjC,MAAI,0BAA0B,QAAW;AACvC,4BAAwB,IAAI,KAAK,WAAW,MAAM;AAAA,MAChD,OAAO;AAAA;AAAA,MAEP,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AACA,SAAO;AACT;AAAA;AAMO,SAAS,WACd,KACA,MACO;AACP,QAAM,YAAY,QAAQ;AAC1B,MAAI,aAAa,GAAG;AAClB,UAAM,IAAI,MAAM,mCAAmC;AAAA,EACrD;AACA,QAAM,EAAE,OAAO,IAAI;AACnB,QAAM,kBAAkB,KAAK,IAAI,QAAQ,SAAS;AAClD,QAAM,SAAS,CAAC;AAChB,WAAS,IAAI,GAAG,IAAI,QAAQ,KAAK,iBAAiB;AAChD,WAAO,KAAK,IAAI,MAAM,GAAG,IAAI,eAAe,CAAQ;AAAA,EACtD;AACA,SAAO;AACT;AAAA;AAMO,SAAS,YAAe,KAA8B;AAC3D,SAAO,CAAC,GAAG,IAAI,IAAI,GAAG,CAAC;AACzB;AAWO,MAAM,UAAU,MAAM;AAAA;AAMtB,SAAS,QAAQ,KAA2C;AACjE,UAAO,wCAAwB,GAAE,OAAO,GAAG;AAC7C;AAAA;AAMO,SAAS,OAAO,KAA2C;AAChE,UAAO,wCAAwB,GAAE,OAAO,GAAG;AAC7C;",
+  "sourcesContent": ["/**\n * @fileoverview Array utility functions for formatting lists and collections.\n * Provides conjunction and disjunction formatters using Intl.ListFormat.\n */\n\nlet _conjunctionFormatter: Intl.ListFormat | undefined\n/**\n * Get a cached Intl.ListFormat instance for conjunction (and) formatting.\n *\n * Creates a singleton formatter for English \"and\" lists using the long style.\n * The formatter is lazily initialized on first use and reused for performance.\n *\n * @returns Cached Intl.ListFormat instance configured for conjunction formatting\n *\n * @example\n * ```ts\n * const formatter = getConjunctionFormatter()\n * formatter.format(['apple', 'banana', 'cherry'])\n * // Returns: \"apple, banana, and cherry\"\n * ```\n *\n * @private\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getConjunctionFormatter() {\n  if (_conjunctionFormatter === undefined) {\n    _conjunctionFormatter = new Intl.ListFormat('en', {\n      style: 'long',\n      // \"and\" lists.\n      type: 'conjunction',\n    })\n  }\n  return _conjunctionFormatter\n}\n\nlet _disjunctionFormatter: Intl.ListFormat | undefined\n/**\n * Get a cached Intl.ListFormat instance for disjunction (or) formatting.\n *\n * Creates a singleton formatter for English \"or\" lists using the long style.\n * The formatter is lazily initialized on first use and reused for performance.\n *\n * @returns Cached Intl.ListFormat instance configured for disjunction formatting\n *\n * @example\n * ```ts\n * const formatter = getDisjunctionFormatter()\n * formatter.format(['red', 'blue', 'green'])\n * // Returns: \"red, blue, or green\"\n * ```\n *\n * @private\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getDisjunctionFormatter() {\n  if (_disjunctionFormatter === undefined) {\n    _disjunctionFormatter = new Intl.ListFormat('en', {\n      style: 'long',\n      // \"or\" lists.\n      type: 'disjunction',\n    })\n  }\n  return _disjunctionFormatter\n}\n\n/**\n * Split an array into chunks of a specified size.\n *\n * Divides an array into smaller arrays of the specified chunk size.\n * The last chunk may contain fewer elements if the array length is not\n * evenly divisible by the chunk size.\n *\n * @param arr - The array to split into chunks (can be readonly)\n * @param size - Size of each chunk. Must be greater than 0.\n * @default 2\n * @returns Array of chunks, where each chunk is an array of elements\n * @throws {Error} If chunk size is less than or equal to 0\n *\n * @example\n * ```ts\n * // Split into pairs (default)\n * arrayChunk([1, 2, 3, 4, 5])\n * // Returns: [[1, 2], [3, 4], [5]]\n *\n * // Split into groups of 3\n * arrayChunk(['a', 'b', 'c', 'd', 'e', 'f', 'g'], 3)\n * // Returns: [['a', 'b', 'c'], ['d', 'e', 'f'], ['g']]\n *\n * // Works with readonly arrays\n * const readonlyArr = [1, 2, 3] as const\n * arrayChunk(readonlyArr)\n * // Returns: [[1, 2], [3]]\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function arrayChunk<T>(\n  arr: T[] | readonly T[],\n  size?: number | undefined,\n): T[][] {\n  const chunkSize = size ?? 2\n  if (chunkSize <= 0) {\n    throw new Error('Chunk size must be greater than 0')\n  }\n  const { length } = arr\n  const actualChunkSize = Math.min(length, chunkSize)\n  const chunks = []\n  for (let i = 0; i < length; i += actualChunkSize) {\n    chunks.push(arr.slice(i, i + actualChunkSize) as T[])\n  }\n  return chunks\n}\n\n/**\n * Get unique values from an array.\n *\n * Returns a new array containing only the unique values from the input array.\n * Uses `Set` internally for efficient deduplication. Order of first occurrence\n * is preserved.\n *\n * @param arr - The array to deduplicate (can be readonly)\n * @returns New array with duplicate values removed\n *\n * @example\n * ```ts\n * // Remove duplicate numbers\n * arrayUnique([1, 2, 2, 3, 1, 4])\n * // Returns: [1, 2, 3, 4]\n *\n * // Remove duplicate strings\n * arrayUnique(['apple', 'banana', 'apple', 'cherry'])\n * // Returns: ['apple', 'banana', 'cherry']\n *\n * // Works with readonly arrays\n * const readonlyArr = [1, 1, 2] as const\n * arrayUnique(readonlyArr)\n * // Returns: [1, 2]\n *\n * // Empty arrays return empty\n * arrayUnique([])\n * // Returns: []\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function arrayUnique<T>(arr: T[] | readonly T[]): T[] {\n  return [...new Set(arr)]\n}\n\n// IMPORTANT: Do not use destructuring here - use direct assignment instead.\n// tsgo has a bug that incorrectly transpiles destructured exports, resulting in\n// `exports.SomeName = void 0;` which causes runtime errors.\n// See: https://github.com/SocketDev/socket-packageurl-js/issues/3\n\n/**\n * Alias for native Array.isArray.\n * Determines whether the passed value is an array.\n *\n * This is a direct reference to the native `Array.isArray` method,\n * providing a type guard that narrows the type to an array type.\n * Exported for consistency with other array utilities in this module.\n *\n * @param value - The value to check\n * @returns `true` if the value is an array, `false` otherwise\n *\n * @example\n * ```ts\n * // Check if value is an array\n * isArray([1, 2, 3])\n * // Returns: true\n *\n * isArray('not an array')\n * // Returns: false\n *\n * isArray(null)\n * // Returns: false\n *\n * // Type guard usage\n * function processValue(value: unknown) {\n *   if (isArray(value)) {\n *     // TypeScript knows value is an array here\n *     console.log(value.length)\n *   }\n * }\n * ```\n */\nexport const isArray = Array.isArray\n\n/**\n * Join array elements with proper \"and\" conjunction formatting.\n *\n * Formats an array of strings into a grammatically correct list using\n * \"and\" as the conjunction. Uses `Intl.ListFormat` for proper English\n * formatting with Oxford comma support.\n *\n * @param arr - Array of strings to join (can be readonly)\n * @returns Formatted string with proper \"and\" conjunction\n *\n * @example\n * ```ts\n * // Two items\n * joinAnd(['apples', 'oranges'])\n * // Returns: \"apples and oranges\"\n *\n * // Three or more items (Oxford comma)\n * joinAnd(['apples', 'oranges', 'bananas'])\n * // Returns: \"apples, oranges, and bananas\"\n *\n * // Single item\n * joinAnd(['apples'])\n * // Returns: \"apples\"\n *\n * // Empty array\n * joinAnd([])\n * // Returns: \"\"\n *\n * // Usage in messages\n * const items = ['React', 'Vue', 'Angular']\n * console.log(`You can choose ${joinAnd(items)}`)\n * // Outputs: \"You can choose React, Vue, and Angular\"\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function joinAnd(arr: string[] | readonly string[]): string {\n  return getConjunctionFormatter().format(arr)\n}\n\n/**\n * Join array elements with proper \"or\" disjunction formatting.\n *\n * Formats an array of strings into a grammatically correct list using\n * \"or\" as the disjunction. Uses `Intl.ListFormat` for proper English\n * formatting with Oxford comma support.\n *\n * @param arr - Array of strings to join (can be readonly)\n * @returns Formatted string with proper \"or\" disjunction\n *\n * @example\n * ```ts\n * // Two items\n * joinOr(['yes', 'no'])\n * // Returns: \"yes or no\"\n *\n * // Three or more items (Oxford comma)\n * joinOr(['red', 'green', 'blue'])\n * // Returns: \"red, green, or blue\"\n *\n * // Single item\n * joinOr(['maybe'])\n * // Returns: \"maybe\"\n *\n * // Empty array\n * joinOr([])\n * // Returns: \"\"\n *\n * // Usage in prompts\n * const options = ['npm', 'yarn', 'pnpm']\n * console.log(`Choose a package manager: ${joinOr(options)}`)\n * // Outputs: \"Choose a package manager: npm, yarn, or pnpm\"\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function joinOr(arr: string[] | readonly string[]): string {\n  return getDisjunctionFormatter().format(arr)\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,IAAI;AAAA;AAmBJ,SAAS,0BAA0B;AACjC,MAAI,0BAA0B,QAAW;AACvC,4BAAwB,IAAI,KAAK,WAAW,MAAM;AAAA,MAChD,OAAO;AAAA;AAAA,MAEP,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AACA,SAAO;AACT;AAEA,IAAI;AAAA;AAmBJ,SAAS,0BAA0B;AACjC,MAAI,0BAA0B,QAAW;AACvC,4BAAwB,IAAI,KAAK,WAAW,MAAM;AAAA,MAChD,OAAO;AAAA;AAAA,MAEP,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AACA,SAAO;AACT;AAAA;AAgCO,SAAS,WACd,KACA,MACO;AACP,QAAM,YAAY,QAAQ;AAC1B,MAAI,aAAa,GAAG;AAClB,UAAM,IAAI,MAAM,mCAAmC;AAAA,EACrD;AACA,QAAM,EAAE,OAAO,IAAI;AACnB,QAAM,kBAAkB,KAAK,IAAI,QAAQ,SAAS;AAClD,QAAM,SAAS,CAAC;AAChB,WAAS,IAAI,GAAG,IAAI,QAAQ,KAAK,iBAAiB;AAChD,WAAO,KAAK,IAAI,MAAM,GAAG,IAAI,eAAe,CAAQ;AAAA,EACtD;AACA,SAAO;AACT;AAAA;AAiCO,SAAS,YAAe,KAA8B;AAC3D,SAAO,CAAC,GAAG,IAAI,IAAI,GAAG,CAAC;AACzB;AAuCO,MAAM,UAAU,MAAM;AAAA;AAqCtB,SAAS,QAAQ,KAA2C;AACjE,UAAO,wCAAwB,GAAE,OAAO,GAAG;AAC7C;AAAA;AAqCO,SAAS,OAAO,KAA2C;AAChE,UAAO,wCAAwB,GAAE,OAAO,GAAG;AAC7C;",
   "names": []
 }

package/dist/effects/text-shimmer.js

@@ -29,6 +29,7 @@ __export(text_shimmer_exports, {
 module.exports = __toCommonJS(text_shimmer_exports);
 var import_ansi = require("../ansi");
 var import_arrays = require("../arrays");
+var import_ci = require("#env/ci");
 function detectStyles(text) {
   return {
     __proto__: null,
@@ -123,7 +124,7 @@ function applyShimmer(text, state, options) {
   const color = opts.color ?? [140, 82, 255];
   const styles = opts.styles ?? detectStyles(text);
   const plainText = (0, import_ansi.stripAnsi)(text);
-  if (!plainText || direction === DIR_NONE) {
+  if (import_ci.CI || !plainText || direction === DIR_NONE) {
     const styleCode = stylesToAnsi(styles);
     const isGradient = (0, import_arrays.isArray)(color[0]);
     return plainText.split("").map((char, i) => {

package/dist/effects/text-shimmer.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/effects/text-shimmer.ts"],
-  "sourcesContent": ["/**\n * @fileoverview Text shimmer animation utilities.\n * Provides animated highlight effects for spinner text with configurable directions:\n * - LTR (left-to-right): Shimmer wave moves from left to right\n * - RTL (right-to-left): Shimmer wave moves from right to left\n * - Bidirectional: Alternates between LTR and RTL each cycle\n * - Random: Picks a random direction each cycle\n * - None: No shimmer animation\n *\n * The shimmer effect creates a bright wave that travels across the text,\n * with characters near the wave appearing nearly white and fading to the\n * base color as they get further from the wave position.\n */\n\nimport { ANSI_RESET, stripAnsi } from '../ansi'\nimport { isArray } from '../arrays'\n\nimport type {\n  ShimmerColorGradient,\n  ShimmerColorRgb,\n  ShimmerDirection,\n  ShimmerState,\n} from './types'\n\n// Re-export types for backward compatibility.\nexport type {\n  ShimmerColor,\n  ShimmerColorGradient,\n  ShimmerColorInherit,\n  ShimmerColorRgb,\n  ShimmerConfig,\n  ShimmerDirection,\n  ShimmerState,\n} from './types'\n\n/**\n * Detected text formatting styles from ANSI codes.\n */\ntype TextStyles = {\n  bold: boolean\n  dim: boolean\n  italic: boolean\n  strikethrough: boolean\n  underline: boolean\n}\n\n/**\n * Detect all text formatting styles present in ANSI-coded text.\n * Checks for bold, dim, italic, underline, and strikethrough.\n */\nfunction detectStyles(text: string): TextStyles {\n  return {\n    __proto__: null,\n    // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequence detection.\n    bold: /\\x1b\\[1m/.test(text),\n    // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequence detection.\n    dim: /\\x1b\\[2m/.test(text),\n    // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequence detection.\n    italic: /\\x1b\\[3m/.test(text),\n    // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequence detection.\n    strikethrough: /\\x1b\\[9m/.test(text),\n    // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequence detection.\n    underline: /\\x1b\\[4m/.test(text),\n  } as TextStyles\n}\n\n/**\n * Build ANSI code string from text styles.\n * Returns the concatenated ANSI codes needed to apply the styles.\n */\nfunction stylesToAnsi(styles: TextStyles): string {\n  let codes = ''\n  if (styles.bold) {\n    codes += '\\x1b[1m'\n  }\n  if (styles.dim) {\n    codes += '\\x1b[2m'\n  }\n  if (styles.italic) {\n    codes += '\\x1b[3m'\n  }\n  if (styles.underline) {\n    codes += '\\x1b[4m'\n  }\n  if (styles.strikethrough) {\n    codes += '\\x1b[9m'\n  }\n  return codes\n}\n\n// Internal options for applyShimmer function.\ntype ShimmerOptions = {\n  readonly color?: ShimmerColorRgb | ShimmerColorGradient | undefined\n  readonly direction?: ShimmerDirection | undefined\n  readonly shimmerWidth?: number | undefined\n  readonly styles?: TextStyles | undefined\n}\n\nexport const COLOR_INHERIT = 'inherit'\n\nexport const DIR_LTR = 'ltr'\n\nexport const DIR_NONE = 'none'\n\nexport const DIR_RANDOM = 'random'\n\nexport const DIR_RTL = 'rtl'\n\nexport const MODE_BI = 'bi'\n\n/**\n * Calculate shimmer intensity based on distance from shimmer wave position.\n * Uses a power curve for smooth falloff - characters close to the wave\n * get high intensity (bright white), while distant characters get 0.\n */\nfunction shimmerIntensity(\n  distance: number,\n  shimmerWidth: number = 2.5,\n): number {\n  // Characters beyond shimmer width get no effect.\n  if (distance > shimmerWidth) {\n    return 0\n  }\n  // Smooth falloff using power curve.\n  const normalized = distance / shimmerWidth\n  return (1 - normalized) ** 2.5\n}\n\n/**\n * Blend two RGB colors based on a blend factor (0-1).\n * factor 0 = color1, factor 1 = color2, factor 0.5 = 50/50 blend.\n */\nfunction blendColors(\n  color1: readonly [number, number, number],\n  color2: readonly [number, number, number],\n  factor: number,\n): readonly [number, number, number] {\n  const r = Math.round(color1[0] + (color2[0] - color1[0]) * factor)\n  const g = Math.round(color1[1] + (color2[1] - color1[1]) * factor)\n  const b = Math.round(color1[2] + (color2[2] - color1[2]) * factor)\n  return [r, g, b] as const\n}\n\n/**\n * Render character with shimmer effect based on distance from shimmer position.\n * Characters closer to the shimmer position get brighter (nearly white),\n * while characters further away use the base color.\n * Creates a smooth gradient by blending base color with white based on intensity.\n * Supports both single color and per-character color gradients.\n */\nfunction renderChar(\n  char: string,\n  index: number,\n  shimmerPos: number,\n  baseColor: readonly [number, number, number] | ShimmerColorGradient,\n  styles: TextStyles,\n): string {\n  // Calculate how far this character is from the shimmer wave.\n  const distance = Math.abs(index - shimmerPos)\n  const intensity = shimmerIntensity(distance)\n\n  const styleCode = stylesToAnsi(styles)\n\n  // Get base color for this character (single or per-character from gradient).\n  const charColor: readonly [number, number, number] = isArray(baseColor[0])\n    ? ((baseColor as ShimmerColorGradient)[index % baseColor.length] ?? [\n        140, 82, 255,\n      ])\n    : (baseColor as readonly [number, number, number])\n\n  // If no shimmer intensity, use base color as-is.\n  if (intensity === 0) {\n    const base = `\\x1b[38;2;${charColor[0]};${charColor[1]};${charColor[2]}m`\n    return `${styleCode}${base}${char}${ANSI_RESET}`\n  }\n\n  // Blend base color with white based on intensity to create smooth gradient.\n  // Higher intensity = more white, creating the shimmer wave effect.\n  const white: readonly [number, number, number] = [255, 255, 255] as const\n  const blended = blendColors(charColor, white, intensity)\n\n  const color = `\\x1b[38;2;${blended[0]};${blended[1]};${blended[2]}m`\n  return `${styleCode}${color}${char}${ANSI_RESET}`\n}\n\n/**\n * Calculate shimmer wave position for current animation step.\n * The shimmer wave moves across the text length, with extra space\n * for the wave to fade in/out at the edges.\n */\nfunction getShimmerPos(\n  textLength: number,\n  step: number,\n  currentDir: 'ltr' | 'rtl',\n  shimmerWidth: number = 2.5,\n): number {\n  // Total steps for one complete cycle (text length + fade in/out space).\n  const totalSteps = textLength + shimmerWidth + 2\n\n  // RTL: Shimmer moves from right to left.\n  if (currentDir === DIR_RTL) {\n    return textLength - (step % totalSteps)\n  }\n\n  // LTR: Shimmer moves from left to right.\n  return step % totalSteps\n}\n\n/**\n * Resolve shimmer direction to a concrete 'ltr' or 'rtl' value.\n * Used for initializing shimmer state and picking random directions.\n */\nfunction pickDirection(direction: ShimmerDirection): 'ltr' | 'rtl' {\n  // Random mode: 50/50 chance of LTR or RTL.\n  if (direction === DIR_RANDOM) {\n    return Math.random() < 0.5 ? DIR_LTR : DIR_RTL\n  }\n  // RTL mode: Use RTL direction.\n  if (direction === DIR_RTL) {\n    return DIR_RTL\n  }\n  // LTR mode (or any other): Default to LTR.\n  return DIR_LTR\n}\n\n/**\n * Apply shimmer animation effect to text.\n * This is the main entry point for shimmer animations. It:\n * 1. Strips ANSI codes to get plain text for character positioning\n * 2. Detects any styling (bold, italic, underline, etc.) to preserve\n * 3. Calculates the current shimmer wave position based on animation step\n * 4. Renders each character with appropriate brightness based on distance from wave\n * 5. Updates the animation state for the next frame\n * 6. Handles direction changes for bidirectional and random modes\n */\nexport function applyShimmer(\n  text: string,\n  state: ShimmerState,\n  options?: ShimmerOptions | undefined,\n): string {\n  const opts = { __proto__: null, ...options } as ShimmerOptions\n  const direction = opts.direction ?? DIR_NONE\n  const shimmerWidth = opts.shimmerWidth ?? 2.5\n  // Socket purple.\n  const color = opts.color ?? ([140, 82, 255] as const)\n\n  // Detect text formatting styles from original text.\n  const styles = opts.styles ?? detectStyles(text)\n\n  // Strip ANSI codes to get plain text.\n  const plainText = stripAnsi(text)\n\n  // No shimmer effect.\n  if (!plainText || direction === DIR_NONE) {\n    const styleCode = stylesToAnsi(styles)\n\n    // Support gradient colors (array of colors, one per character).\n    const isGradient = isArray(color[0])\n\n    return plainText\n      .split('')\n      .map((char, i) => {\n        const charColor: readonly [number, number, number] = isGradient\n          ? ((color as ShimmerColorGradient)[i % color.length] ?? [\n              140, 82, 255,\n            ])\n          : (color as readonly [number, number, number])\n        const base = `\\x1b[38;2;${charColor[0]};${charColor[1]};${charColor[2]}m`\n        return `${styleCode}${base}${char}${ANSI_RESET}`\n      })\n      .join('')\n  }\n\n  // Calculate shimmer position.\n  const shimmerPos = getShimmerPos(\n    plainText.length,\n    state.step,\n    state.currentDir,\n    shimmerWidth,\n  )\n\n  // Render text with shimmer.\n  const result = plainText\n    .split('')\n    .map((char, i) => renderChar(char, i, shimmerPos, color, styles))\n    .join('')\n\n  // Advance shimmer position by speed amount each frame.\n  // Speed represents steps per frame (e.g., 0.33 = advance 0.33 steps per frame).\n  // This creates smooth animation by moving in small increments every frame\n  // instead of jumping larger distances every N frames.\n  state.step += state.speed\n\n  // Handle bidirectional direction changes.\n  const totalSteps = plainText.length + shimmerWidth + 2\n  if (state.mode === MODE_BI) {\n    if (state.step >= totalSteps) {\n      state.step = 0\n      // Toggle direction every cycle.\n      state.currentDir = state.currentDir === DIR_LTR ? DIR_RTL : DIR_LTR\n    }\n  } else if (state.mode === DIR_RANDOM) {\n    // Change direction randomly at end of each cycle.\n    if (state.step >= totalSteps) {\n      state.step = 0\n      state.currentDir = pickDirection(DIR_RANDOM)\n    }\n  } else {\n    // Reset for continuous loops.\n    if (state.step >= totalSteps) {\n      state.step = 0\n    }\n  }\n\n  return result\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * @fileoverview Text shimmer animation utilities.\n * Provides animated highlight effects for spinner text with configurable directions:\n * - LTR (left-to-right): Shimmer wave moves from left to right\n * - RTL (right-to-left): Shimmer wave moves from right to left\n * - Bidirectional: Alternates between LTR and RTL each cycle\n * - Random: Picks a random direction each cycle\n * - None: No shimmer animation\n *\n * The shimmer effect creates a bright wave that travels across the text,\n * with characters near the wave appearing nearly white and fading to the\n * base color as they get further from the wave position.\n */\n\nimport { ANSI_RESET, stripAnsi } from '../ansi'\nimport { isArray } from '../arrays'\nimport { CI } from '#env/ci'\n\nimport type {\n  ShimmerColorGradient,\n  ShimmerColorRgb,\n  ShimmerDirection,\n  ShimmerState,\n} from './types'\n\n// Re-export types for backward compatibility.\nexport type {\n  ShimmerColor,\n  ShimmerColorGradient,\n  ShimmerColorInherit,\n  ShimmerColorRgb,\n  ShimmerConfig,\n  ShimmerDirection,\n  ShimmerState,\n} from './types'\n\n/**\n * Detected text formatting styles from ANSI codes.\n */\ntype TextStyles = {\n  bold: boolean\n  dim: boolean\n  italic: boolean\n  strikethrough: boolean\n  underline: boolean\n}\n\n/**\n * Detect all text formatting styles present in ANSI-coded text.\n * Checks for bold, dim, italic, underline, and strikethrough.\n */\nfunction detectStyles(text: string): TextStyles {\n  return {\n    __proto__: null,\n    // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequence detection.\n    bold: /\\x1b\\[1m/.test(text),\n    // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequence detection.\n    dim: /\\x1b\\[2m/.test(text),\n    // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequence detection.\n    italic: /\\x1b\\[3m/.test(text),\n    // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequence detection.\n    strikethrough: /\\x1b\\[9m/.test(text),\n    // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequence detection.\n    underline: /\\x1b\\[4m/.test(text),\n  } as TextStyles\n}\n\n/**\n * Build ANSI code string from text styles.\n * Returns the concatenated ANSI codes needed to apply the styles.\n */\nfunction stylesToAnsi(styles: TextStyles): string {\n  let codes = ''\n  if (styles.bold) {\n    codes += '\\x1b[1m'\n  }\n  if (styles.dim) {\n    codes += '\\x1b[2m'\n  }\n  if (styles.italic) {\n    codes += '\\x1b[3m'\n  }\n  if (styles.underline) {\n    codes += '\\x1b[4m'\n  }\n  if (styles.strikethrough) {\n    codes += '\\x1b[9m'\n  }\n  return codes\n}\n\n// Internal options for applyShimmer function.\ntype ShimmerOptions = {\n  readonly color?: ShimmerColorRgb | ShimmerColorGradient | undefined\n  readonly direction?: ShimmerDirection | undefined\n  readonly shimmerWidth?: number | undefined\n  readonly styles?: TextStyles | undefined\n}\n\nexport const COLOR_INHERIT = 'inherit'\n\nexport const DIR_LTR = 'ltr'\n\nexport const DIR_NONE = 'none'\n\nexport const DIR_RANDOM = 'random'\n\nexport const DIR_RTL = 'rtl'\n\nexport const MODE_BI = 'bi'\n\n/**\n * Calculate shimmer intensity based on distance from shimmer wave position.\n * Uses a power curve for smooth falloff - characters close to the wave\n * get high intensity (bright white), while distant characters get 0.\n */\nfunction shimmerIntensity(\n  distance: number,\n  shimmerWidth: number = 2.5,\n): number {\n  // Characters beyond shimmer width get no effect.\n  if (distance > shimmerWidth) {\n    return 0\n  }\n  // Smooth falloff using power curve.\n  const normalized = distance / shimmerWidth\n  return (1 - normalized) ** 2.5\n}\n\n/**\n * Blend two RGB colors based on a blend factor (0-1).\n * factor 0 = color1, factor 1 = color2, factor 0.5 = 50/50 blend.\n */\nfunction blendColors(\n  color1: readonly [number, number, number],\n  color2: readonly [number, number, number],\n  factor: number,\n): readonly [number, number, number] {\n  const r = Math.round(color1[0] + (color2[0] - color1[0]) * factor)\n  const g = Math.round(color1[1] + (color2[1] - color1[1]) * factor)\n  const b = Math.round(color1[2] + (color2[2] - color1[2]) * factor)\n  return [r, g, b] as const\n}\n\n/**\n * Render character with shimmer effect based on distance from shimmer position.\n * Characters closer to the shimmer position get brighter (nearly white),\n * while characters further away use the base color.\n * Creates a smooth gradient by blending base color with white based on intensity.\n * Supports both single color and per-character color gradients.\n */\nfunction renderChar(\n  char: string,\n  index: number,\n  shimmerPos: number,\n  baseColor: readonly [number, number, number] | ShimmerColorGradient,\n  styles: TextStyles,\n): string {\n  // Calculate how far this character is from the shimmer wave.\n  const distance = Math.abs(index - shimmerPos)\n  const intensity = shimmerIntensity(distance)\n\n  const styleCode = stylesToAnsi(styles)\n\n  // Get base color for this character (single or per-character from gradient).\n  const charColor: readonly [number, number, number] = isArray(baseColor[0])\n    ? ((baseColor as ShimmerColorGradient)[index % baseColor.length] ?? [\n        140, 82, 255,\n      ])\n    : (baseColor as readonly [number, number, number])\n\n  // If no shimmer intensity, use base color as-is.\n  if (intensity === 0) {\n    const base = `\\x1b[38;2;${charColor[0]};${charColor[1]};${charColor[2]}m`\n    return `${styleCode}${base}${char}${ANSI_RESET}`\n  }\n\n  // Blend base color with white based on intensity to create smooth gradient.\n  // Higher intensity = more white, creating the shimmer wave effect.\n  const white: readonly [number, number, number] = [255, 255, 255] as const\n  const blended = blendColors(charColor, white, intensity)\n\n  const color = `\\x1b[38;2;${blended[0]};${blended[1]};${blended[2]}m`\n  return `${styleCode}${color}${char}${ANSI_RESET}`\n}\n\n/**\n * Calculate shimmer wave position for current animation step.\n * The shimmer wave moves across the text length, with extra space\n * for the wave to fade in/out at the edges.\n */\nfunction getShimmerPos(\n  textLength: number,\n  step: number,\n  currentDir: 'ltr' | 'rtl',\n  shimmerWidth: number = 2.5,\n): number {\n  // Total steps for one complete cycle (text length + fade in/out space).\n  const totalSteps = textLength + shimmerWidth + 2\n\n  // RTL: Shimmer moves from right to left.\n  if (currentDir === DIR_RTL) {\n    return textLength - (step % totalSteps)\n  }\n\n  // LTR: Shimmer moves from left to right.\n  return step % totalSteps\n}\n\n/**\n * Resolve shimmer direction to a concrete 'ltr' or 'rtl' value.\n * Used for initializing shimmer state and picking random directions.\n */\nfunction pickDirection(direction: ShimmerDirection): 'ltr' | 'rtl' {\n  // Random mode: 50/50 chance of LTR or RTL.\n  if (direction === DIR_RANDOM) {\n    return Math.random() < 0.5 ? DIR_LTR : DIR_RTL\n  }\n  // RTL mode: Use RTL direction.\n  if (direction === DIR_RTL) {\n    return DIR_RTL\n  }\n  // LTR mode (or any other): Default to LTR.\n  return DIR_LTR\n}\n\n/**\n * Apply shimmer animation effect to text.\n * This is the main entry point for shimmer animations. It:\n * 1. Strips ANSI codes to get plain text for character positioning\n * 2. Detects any styling (bold, italic, underline, etc.) to preserve\n * 3. Calculates the current shimmer wave position based on animation step\n * 4. Renders each character with appropriate brightness based on distance from wave\n * 5. Updates the animation state for the next frame\n * 6. Handles direction changes for bidirectional and random modes\n */\nexport function applyShimmer(\n  text: string,\n  state: ShimmerState,\n  options?: ShimmerOptions | undefined,\n): string {\n  const opts = { __proto__: null, ...options } as ShimmerOptions\n  const direction = opts.direction ?? DIR_NONE\n  const shimmerWidth = opts.shimmerWidth ?? 2.5\n  // Socket purple.\n  const color = opts.color ?? ([140, 82, 255] as const)\n\n  // Detect text formatting styles from original text.\n  const styles = opts.styles ?? detectStyles(text)\n\n  // Strip ANSI codes to get plain text.\n  const plainText = stripAnsi(text)\n\n  // No shimmer effect in CI or when direction is 'none'.\n  if (CI || !plainText || direction === DIR_NONE) {\n    const styleCode = stylesToAnsi(styles)\n\n    // Support gradient colors (array of colors, one per character).\n    const isGradient = isArray(color[0])\n\n    return plainText\n      .split('')\n      .map((char, i) => {\n        const charColor: readonly [number, number, number] = isGradient\n          ? ((color as ShimmerColorGradient)[i % color.length] ?? [\n              140, 82, 255,\n            ])\n          : (color as readonly [number, number, number])\n        const base = `\\x1b[38;2;${charColor[0]};${charColor[1]};${charColor[2]}m`\n        return `${styleCode}${base}${char}${ANSI_RESET}`\n      })\n      .join('')\n  }\n\n  // Calculate shimmer position.\n  const shimmerPos = getShimmerPos(\n    plainText.length,\n    state.step,\n    state.currentDir,\n    shimmerWidth,\n  )\n\n  // Render text with shimmer.\n  const result = plainText\n    .split('')\n    .map((char, i) => renderChar(char, i, shimmerPos, color, styles))\n    .join('')\n\n  // Advance shimmer position by speed amount each frame.\n  // Speed represents steps per frame (e.g., 0.33 = advance 0.33 steps per frame).\n  // This creates smooth animation by moving in small increments every frame\n  // instead of jumping larger distances every N frames.\n  state.step += state.speed\n\n  // Handle bidirectional direction changes.\n  const totalSteps = plainText.length + shimmerWidth + 2\n  if (state.mode === MODE_BI) {\n    if (state.step >= totalSteps) {\n      state.step = 0\n      // Toggle direction every cycle.\n      state.currentDir = state.currentDir === DIR_LTR ? DIR_RTL : DIR_LTR\n    }\n  } else if (state.mode === DIR_RANDOM) {\n    // Change direction randomly at end of each cycle.\n    if (state.step >= totalSteps) {\n      state.step = 0\n      state.currentDir = pickDirection(DIR_RANDOM)\n    }\n  } else {\n    // Reset for continuous loops.\n    if (state.step >= totalSteps) {\n      state.step = 0\n    }\n  }\n\n  return result\n}\n"],
+  "mappings": "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",
   "names": []
 }