@thegetty/quire-cli 1.0.0-rc.44 → 1.0.0-rc.46

package/src/lib/reporter/index.js

@@ -1,607 +0,0 @@
-/**
- * Reporter module for CLI progress feedback
- *
- * Provides a consistent interface for progress indicators (spinners) with
- * unified handling of quiet/verbose modes and testability. Follows the
- * singleton pattern like lib/logger.js for easy mocking in tests.
- *
- * ## Output Modes
- *
- * The reporter supports three output modes controlled by command options:
- *
- * | Mode | Flag | Behavior |
- * |------|------|----------|
- * | Default | (none) | Show spinner with basic status |
- * | Quiet | `-q, --quiet` | Suppress all output (for CI/scripts) |
- * | Verbose | `-v, --verbose` | Show detailed progress with paths, timing |
- * | Reduced Motion | `--reduced-motion` | Static text, no animation, no line overwriting |
- *
- * Note: `--debug` is handled separately and enables DEBUG namespace logging,
- * not reporter output. Use verbose mode for detailed user-facing output.
- *
- * ## Reduced Motion
- *
- * When reduced motion is enabled (via `--reduced-motion` flag, `REDUCED_MOTION`
- * environment variable, or `reducedMotion` config setting), the reporter:
- * - Prints static text instead of animated spinners
- * - Outputs each stage on a new line (no line overwriting)
- * - Still shows status symbols (✔ ✖ ⚠ ℹ) for completion states
- *
- * This mode is designed for screen reader users and environments where
- * terminal animation is problematic.
- *
- * ## Config Defaults
- *
- * Users can set default values via `quire settings`:
- * - `quire settings set verbose true` - Always run in verbose mode
- * - `quire settings set reducedMotion true` - Disable spinner animation
- *
- * CLI flags override config settings. Use `--no-verbose` to disable verbose
- * mode even when enabled in config.
- *
- * @example Production usage
- * import reporter from '#lib/reporter/index.js'
- * reporter.start('Building site...')
- * await build()
- * reporter.succeed('Build complete')
- *
- * @example Multi-phase operation
- * reporter.start('Cloning starter...')
- * await git.clone()
- * reporter.update('Installing dependencies...')
- * await npm.install()
- * reporter.succeed('Project created')
- *
- * @example Error handling
- * reporter.start('Generating PDF...')
- * try {
- *   await generatePdf()
- *   reporter.succeed()
- * } catch (error) {
- *   reporter.fail('PDF generation failed')
- *   throw error
- * }
- *
- * @example Verbose mode with details
- * reporter.configure({ verbose: true })
- * reporter.start('Building site...')
- * reporter.detail('Output: _site/')
- * reporter.detail('Pages: 45')
- * reporter.succeed('Build complete')
- * // Shows:
- * // ⠋ Building site...
- * //   Output: _site/
- * //   Pages: 45
- * // ✔ Build complete
- *
- * @example Test mocking
- * const mockReporter = {
- *   start: sandbox.stub(),
- *   succeed: sandbox.stub(),
- *   fail: sandbox.stub(),
- *   configure: sandbox.stub(),
- * }
- * const MyCommand = await esmock('./mycommand.js', {
- *   '#lib/reporter/index.js': { default: mockReporter }
- * })
- *
- * @see https://github.com/sindresorhus/ora
- * @module lib/reporter
- */
-import ora from 'ora'
-import createDebug from '#debug'
-import config from '#lib/conf/config.js'
-
-const debug = createDebug('lib:reporter')
-
-/**
- * Status symbols for reduced motion output
- *
- * These match the symbols used by ora for visual consistency,
- * ensuring the same information is conveyed with or without animation.
- * @private
- */
-const STATUS_SYMBOLS = {
-  start: '–',
-  succeed: '✔',
-  fail: '✖',
-  warn: '⚠',
-  info: 'ℹ',
-}
-
-/**
- * Reporter class for CLI progress feedback
- *
- * Wraps ora spinner with additional features:
- * - Respects --quiet and --json flags
- * - Supports reduced motion (static text, no line overwriting)
- * - Supports elapsed time display
- * - Provides consistent API across commands
- */
-class Reporter {
-  /** @type {import('ora').Ora|null} */
-  #spinner = null
-
-  /** @type {boolean} */
-  #quiet = false
-
-  /** @type {boolean} */
-  #json = false
-
-  /** @type {boolean} */
-  #verbose = false
-
-  /** @type {number|null} */
-  #startTime = null
-
-  /** @type {NodeJS.Timeout|null} */
-  #elapsedInterval = null
-
-  /** @type {string} */
-  #baseText = ''
-
-  /**
-   * Check if reduced motion mode is active
-   *
-   * Reduced motion disables spinner animation and line overwriting.
-   * Reads from the REDUCED_MOTION environment variable, which is set by:
-   * - `--reduced-motion` CLI flag (via preAction hook)
-   * - `REDUCED_MOTION=1` shell environment variable
-   * - `reducedMotion: true` config setting (via bin/cli.js)
-   *
-   * @private
-   * @returns {boolean}
-   */
-  #isReducedMotion() {
-    return Boolean(process.env.REDUCED_MOTION)
-  }
-
-  /**
-   * Configure reporter for current command context
-   *
-   * Call this at the start of command action() to respect command options.
-   * CLI flags take precedence over config settings.
-   *
-   * @param {Object} options - Command options
-   * @param {boolean} [options.quiet] - Suppress all output (no config default)
-   * @param {boolean} [options.json] - JSON output mode (suppress spinner)
-   * @param {boolean} [options.verbose] - Verbose output mode (falls back to config.verbose)
-   * @returns {Reporter} this instance for chaining
-   *
-   * @example
-   * async action(options) {
-   *   reporter.configure(options)
-   *   reporter.start('Working...')
-   * }
-   */
-  configure(options = {}) {
-    this.#quiet = options.quiet || false
-    this.#json = options.json || false
-    // CLI flag takes precedence, then config setting, then default false
-    this.#verbose = options.verbose ?? config.get('verbose') ?? false
-    debug('configured: quiet=%s, json=%s, verbose=%s, reducedMotion=%s',
-      this.#quiet, this.#json, this.#verbose, this.#isReducedMotion())
-    return this
-  }
-
-  /**
-   * Check if output should be suppressed
-   * @private
-   * @returns {boolean}
-   */
-  #shouldSuppress() {
-    // Suppress if quiet mode, JSON mode, or not a TTY
-    return this.#quiet || this.#json || !process.stdout.isTTY
-  }
-
-  /**
-   * Start a new spinner
-   *
-   * @param {string} text - Initial spinner text
-   * @param {Object} [options] - Spinner options
-   * @param {boolean} [options.showElapsed=false] - Show elapsed time (e.g., "Building... (12s)")
-   * @returns {Reporter} this instance for chaining
-   *
-   * @example
-   * reporter.start('Building site...')
-   *
-   * @example With elapsed time
-   * reporter.start('Building site...', { showElapsed: true })
-   * // Shows: ⠋ Building site... (12s)
-   */
-  start(text, options = {}) {
-    // Stop any existing spinner
-    this.stop()
-
-    this.#baseText = text
-    this.#startTime = Date.now()
-
-    if (this.#shouldSuppress()) {
-      debug('spinner suppressed: %s', text)
-      return this
-    }
-
-    // Reduced motion: print static text on a new line, no spinner
-    if (this.#isReducedMotion()) {
-      debug('spinner start (reduced motion): %s', text)
-      console.log(`${STATUS_SYMBOLS.start} ${text}`)
-      return this
-    }
-
-    debug('spinner start: %s', text)
-    this.#spinner = ora({
-      text,
-      // Use 'dots' spinner for consistency across platforms
-      spinner: 'dots',
-    }).start()
-
-    // Start elapsed time updates if requested
-    if (options.showElapsed) {
-      this.#startElapsedTimer()
-    }
-
-    return this
-  }
-
-  /**
-   * Start interval timer to update elapsed time display
-   * @private
-   */
-  #startElapsedTimer() {
-    this.#elapsedInterval = setInterval(() => {
-      if (this.#spinner && this.#startTime) {
-        const elapsed = Math.floor((Date.now() - this.#startTime) / 1000)
-        this.#spinner.text = `${this.#baseText} (${elapsed}s)`
-      }
-    }, 1000)
-  }
-
-  /**
-   * Stop elapsed time timer
-   * @private
-   */
-  #stopElapsedTimer() {
-    if (this.#elapsedInterval) {
-      clearInterval(this.#elapsedInterval)
-      this.#elapsedInterval = null
-    }
-  }
-
-  /**
-   * Update spinner text while running
-   *
-   * @param {string} text - New spinner text
-   * @returns {Reporter} this instance for chaining
-   *
-   * @example
-   * reporter.start('Step 1...')
-   * await step1()
-   * reporter.update('Step 2...')
-   * await step2()
-   * reporter.succeed('All steps complete')
-   */
-  update(text) {
-    this.#baseText = text
-
-    if (this.#shouldSuppress()) {
-      debug('spinner update (suppressed): %s', text)
-      return this
-    }
-
-    // Reduced motion: print new line instead of overwriting
-    if (this.#isReducedMotion()) {
-      debug('spinner update (reduced motion): %s', text)
-      console.log(`${STATUS_SYMBOLS.start} ${text}`)
-      return this
-    }
-
-    if (this.#spinner) {
-      debug('spinner update: %s', text)
-      this.#spinner.text = text
-    } else {
-      // If no spinner running, start one
-      this.start(text)
-    }
-
-    return this
-  }
-
-  /**
-   * Mark operation as successful
-   *
-   * @param {string} [text] - Optional success message (defaults to current text)
-   * @returns {Reporter} this instance for chaining
-   *
-   * @example
-   * reporter.start('Building...')
-   * await build()
-   * reporter.succeed('Build complete')
-   *
-   * @example Using current text
-   * reporter.start('Building site...')
-   * await build()
-   * reporter.succeed() // Shows: ✔ Building site...
-   */
-  succeed(text) {
-    this.#stopElapsedTimer()
-
-    const message = text || this.#baseText
-
-    if (this.#shouldSuppress()) {
-      debug('spinner succeed (suppressed): %s', message)
-      this.#spinner = null
-      return this
-    }
-
-    // Reduced motion: print static success line
-    if (this.#isReducedMotion()) {
-      debug('spinner succeed (reduced motion): %s', message)
-      console.log(`${STATUS_SYMBOLS.succeed} ${message}`)
-      return this
-    }
-
-    if (this.#spinner) {
-      debug('spinner succeed: %s', message)
-      this.#spinner.succeed(message)
-      this.#spinner = null
-    }
-
-    return this
-  }
-
-  /**
-   * Mark operation as failed
-   *
-   * @param {string} [text] - Optional failure message (defaults to current text)
-   * @returns {Reporter} this instance for chaining
-   *
-   * @example
-   * reporter.start('Generating PDF...')
-   * try {
-   *   await generatePdf()
-   *   reporter.succeed()
-   * } catch (error) {
-   *   reporter.fail('PDF generation failed')
-   *   throw error
-   * }
-   */
-  fail(text) {
-    this.#stopElapsedTimer()
-
-    const message = text || this.#baseText
-
-    if (this.#shouldSuppress()) {
-      debug('spinner fail (suppressed): %s', message)
-      this.#spinner = null
-      return this
-    }
-
-    // Reduced motion: print static failure line
-    if (this.#isReducedMotion()) {
-      debug('spinner fail (reduced motion): %s', message)
-      console.log(`${STATUS_SYMBOLS.fail} ${message}`)
-      return this
-    }
-
-    if (this.#spinner) {
-      debug('spinner fail: %s', message)
-      this.#spinner.fail(message)
-      this.#spinner = null
-    }
-
-    return this
-  }
-
-  /**
-   * Mark operation with a warning
-   *
-   * @param {string} [text] - Optional warning message (defaults to current text)
-   * @returns {Reporter} this instance for chaining
-   *
-   * @example
-   * reporter.start('Checking dependencies...')
-   * if (outdatedDeps.length > 0) {
-   *   reporter.warn('Some dependencies are outdated')
-   * } else {
-   *   reporter.succeed('All dependencies up to date')
-   * }
-   */
-  warn(text) {
-    this.#stopElapsedTimer()
-
-    const message = text || this.#baseText
-
-    if (this.#shouldSuppress()) {
-      debug('spinner warn (suppressed): %s', message)
-      this.#spinner = null
-      return this
-    }
-
-    // Reduced motion: print static warning line
-    if (this.#isReducedMotion()) {
-      debug('spinner warn (reduced motion): %s', message)
-      console.log(`${STATUS_SYMBOLS.warn} ${message}`)
-      return this
-    }
-
-    if (this.#spinner) {
-      debug('spinner warn: %s', message)
-      this.#spinner.warn(message)
-      this.#spinner = null
-    }
-
-    return this
-  }
-
-  /**
-   * Display an info message (non-spinner)
-   *
-   * @param {string} text - Info message
-   * @returns {Reporter} this instance for chaining
-   *
-   * @example
-   * reporter.info('Using cached dependencies')
-   */
-  info(text) {
-    this.#stopElapsedTimer()
-
-    if (this.#shouldSuppress()) {
-      debug('spinner info (suppressed): %s', text)
-      this.#spinner = null
-      return this
-    }
-
-    // Reduced motion: print static info line
-    if (this.#isReducedMotion()) {
-      debug('spinner info (reduced motion): %s', text)
-      console.log(`${STATUS_SYMBOLS.info} ${text}`)
-      return this
-    }
-
-    if (this.#spinner) {
-      debug('spinner info: %s', text)
-      this.#spinner.info(text)
-      this.#spinner = null
-    } else {
-      // Create temporary spinner just to show info
-      ora().info(text)
-    }
-
-    return this
-  }
-
-  /**
-   * Display a detail line (only shown in verbose mode)
-   *
-   * Use this to provide additional context that's useful for users
-   * who want more information but isn't essential for normal operation.
-   *
-   * @param {string} text - Detail text to display
-   * @returns {Reporter} this instance for chaining
-   *
-   * @example
-   * reporter.configure({ verbose: true })
-   * reporter.start('Building site...')
-   * reporter.detail('Output: _site/')
-   * reporter.detail('Processing 45 pages')
-   * reporter.succeed('Build complete')
-   */
-  detail(text) {
-    // Only show details in verbose mode
-    if (!this.#verbose || this.#shouldSuppress()) {
-      debug('detail (suppressed): %s', text)
-      return this
-    }
-
-    // Reduced motion: print detail directly (no spinner to stop/restart)
-    if (this.#isReducedMotion()) {
-      console.log(`  ${text}`)
-      debug('detail (reduced motion): %s', text)
-      return this
-    }
-
-    // Print detail with indentation below spinner
-    if (this.#spinner) {
-      // Temporarily stop spinner to print detail
-      const wasSpinning = this.#spinner.isSpinning
-      if (wasSpinning) {
-        this.#spinner.stop()
-      }
-      console.log(`  ${text}`)
-      if (wasSpinning) {
-        this.#spinner.start()
-      }
-    } else {
-      console.log(`  ${text}`)
-    }
-
-    debug('detail: %s', text)
-    return this
-  }
-
-  /**
-   * Check if verbose mode is enabled
-   *
-   * @returns {boolean} True if verbose mode is enabled
-   */
-  isVerbose() {
-    return this.#verbose
-  }
-
-  /**
-   * Stop spinner without status indicator
-   *
-   * Use this when an operation is interrupted or when you need
-   * to clear the spinner before other output.
-   *
-   * @returns {Reporter} this instance for chaining
-   *
-   * @example
-   * reporter.start('Processing...')
-   * if (shouldAbort) {
-   *   reporter.stop()
-   *   return
-   * }
-   */
-  stop() {
-    this.#stopElapsedTimer()
-
-    if (this.#spinner) {
-      debug('spinner stop')
-      this.#spinner.stop()
-      this.#spinner = null
-    }
-
-    return this
-  }
-
-  /**
-   * Check if spinner is currently active
-   *
-   * @returns {boolean} True if a spinner is running
-   *
-   * @example
-   * if (reporter.isSpinning()) {
-   *   reporter.stop()
-   * }
-   */
-  isSpinning() {
-    return this.#spinner !== null && this.#spinner.isSpinning
-  }
-
-  /**
-   * Get elapsed time since spinner started
-   *
-   * @returns {number|null} Elapsed time in milliseconds, or null if not started
-   */
-  getElapsed() {
-    if (this.#startTime === null) {
-      return null
-    }
-    return Date.now() - this.#startTime
-  }
-
-  /**
-   * Reset reporter state
-   *
-   * Useful for testing or when reusing reporter across multiple operations.
-   *
-   * @returns {Reporter} this instance for chaining
-   */
-  reset() {
-    this.stop()
-    this.#quiet = false
-    this.#json = false
-    this.#verbose = false
-    this.#startTime = null
-    this.#baseText = ''
-    debug('reporter reset')
-    return this
-  }
-}
-
-// Export singleton instance
-export default new Reporter()
-
-// Export class for testing
-export { Reporter }