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

package/src/lib/doctor/formatDuration.js

@@ -1,108 +0,0 @@
-/**
- * Duration formatting utilities for doctor module
- *
- * Provides human-readable time duration formatting for diagnostic checks,
- * particularly useful for displaying how stale a build output is compared
- * to source files.
- *
- * The stale build check uses this to display appropriate durations like
- * "Build output is 2 weeks older than source files" or
- * "Build output is 3 months older than source files" for long-abandoned builds.
- *
- * @module lib/doctor/formatDuration
- */
-
-/**
- * Time unit definitions in milliseconds
- * @constant {Object}
- */
-const TIME_UNITS = {
-  second: 1000,
-  minute: 60 * 1000,
-  hour: 60 * 60 * 1000,
-  day: 24 * 60 * 60 * 1000,
-  week: 7 * 24 * 60 * 60 * 1000,
-  month: 30 * 24 * 60 * 60 * 1000,
-  year: 365 * 24 * 60 * 60 * 1000,
-}
-
-/**
- * Format a duration in milliseconds as a human-readable string.
- *
- * Converts a time duration to the most appropriate unit (seconds through years),
- * using singular or plural form as needed. The function selects the largest
- * applicable unit to keep output concise.
- *
- * ## Duration Thresholds
- *
- * | Duration       | Example Output  |
- * |----------------|-----------------|
- * | < 1 minute     | "45 seconds"    |
- * | < 1 hour       | "30 minutes"    |
- * | < 1 day        | "5 hours"       |
- * | < 1 week       | "3 days"        |
- * | < 1 month      | "2 weeks"       |
- * | < 1 year       | "3 months"      |
- * | >= 1 year      | "2 years"       |
- *
- * @param {number} ms - Duration in milliseconds. Must be a non-negative number.
- *
- * @returns {string} Human-readable duration string with unit.
- *
- * @example
- * // Returns "45 seconds"
- * formatDuration(45000)
- *
- * @example
- * // Returns "1 hour"
- * formatDuration(3600000)
- *
- * @example
- * // Returns "2 weeks"
- * formatDuration(14 * 24 * 60 * 60 * 1000)
- *
- * @example
- * // Returns "3 months"
- * formatDuration(90 * 24 * 60 * 60 * 1000)
- *
- * @example
- * // Returns "1 year"
- * formatDuration(365 * 24 * 60 * 60 * 1000)
- *
- * @remarks
- * - Uses approximate values for months (30 days) and years (365 days)
- * - Always returns the largest applicable unit (e.g., "2 weeks" not "14 days")
- * - Handles singular/plural forms automatically
- * - Returns "0 seconds" for zero or negative input
- */
-export function formatDuration(ms) {
-  const seconds = Math.floor(ms / TIME_UNITS.second)
-  const minutes = Math.floor(ms / TIME_UNITS.minute)
-  const hours = Math.floor(ms / TIME_UNITS.hour)
-  const days = Math.floor(ms / TIME_UNITS.day)
-  const weeks = Math.floor(ms / TIME_UNITS.week)
-  const months = Math.floor(ms / TIME_UNITS.month)
-  const years = Math.floor(ms / TIME_UNITS.year)
-
-  if (years > 0) {
-    return `${years} year${years === 1 ? '' : 's'}`
-  }
-  if (months > 0) {
-    return `${months} month${months === 1 ? '' : 's'}`
-  }
-  if (weeks > 0) {
-    return `${weeks} week${weeks === 1 ? '' : 's'}`
-  }
-  if (days > 0) {
-    return `${days} day${days === 1 ? '' : 's'}`
-  }
-  if (hours > 0) {
-    return `${hours} hour${hours === 1 ? '' : 's'}`
-  }
-  if (minutes > 0) {
-    return `${minutes} minute${minutes === 1 ? '' : 's'}`
-  }
-  return `${seconds} second${seconds === 1 ? '' : 's'}`
-}
-
-export default formatDuration

package/src/lib/doctor/formatDuration.test.js

@@ -1,76 +0,0 @@
-import test from 'ava'
-import { formatDuration } from './formatDuration.js'
-
-test('formatDuration returns seconds for durations under 1 minute', (t) => {
-  t.is(formatDuration(0), '0 seconds')
-  t.is(formatDuration(1000), '1 second')
-  t.is(formatDuration(45000), '45 seconds')
-  t.is(formatDuration(59000), '59 seconds')
-})
-
-test('formatDuration returns minutes for durations under 1 hour', (t) => {
-  t.is(formatDuration(60000), '1 minute')
-  t.is(formatDuration(120000), '2 minutes')
-  t.is(formatDuration(30 * 60 * 1000), '30 minutes')
-  t.is(formatDuration(59 * 60 * 1000), '59 minutes')
-})
-
-test('formatDuration returns hours for durations under 1 day', (t) => {
-  t.is(formatDuration(60 * 60 * 1000), '1 hour')
-  t.is(formatDuration(2 * 60 * 60 * 1000), '2 hours')
-  t.is(formatDuration(12 * 60 * 60 * 1000), '12 hours')
-  t.is(formatDuration(23 * 60 * 60 * 1000), '23 hours')
-})
-
-test('formatDuration returns days for durations under 1 week', (t) => {
-  t.is(formatDuration(24 * 60 * 60 * 1000), '1 day')
-  t.is(formatDuration(2 * 24 * 60 * 60 * 1000), '2 days')
-  t.is(formatDuration(6 * 24 * 60 * 60 * 1000), '6 days')
-})
-
-test('formatDuration returns weeks for durations under 1 month', (t) => {
-  t.is(formatDuration(7 * 24 * 60 * 60 * 1000), '1 week')
-  t.is(formatDuration(14 * 24 * 60 * 60 * 1000), '2 weeks')
-  t.is(formatDuration(21 * 24 * 60 * 60 * 1000), '3 weeks')
-  t.is(formatDuration(28 * 24 * 60 * 60 * 1000), '4 weeks')
-})
-
-test('formatDuration returns months for durations under 1 year', (t) => {
-  t.is(formatDuration(30 * 24 * 60 * 60 * 1000), '1 month')
-  t.is(formatDuration(60 * 24 * 60 * 60 * 1000), '2 months')
-  t.is(formatDuration(90 * 24 * 60 * 60 * 1000), '3 months')
-  t.is(formatDuration(180 * 24 * 60 * 60 * 1000), '6 months')
-  t.is(formatDuration(364 * 24 * 60 * 60 * 1000), '12 months')
-})
-
-test('formatDuration returns years for durations of 1 year or more', (t) => {
-  t.is(formatDuration(365 * 24 * 60 * 60 * 1000), '1 year')
-  t.is(formatDuration(2 * 365 * 24 * 60 * 60 * 1000), '2 years')
-  t.is(formatDuration(5 * 365 * 24 * 60 * 60 * 1000), '5 years')
-  t.is(formatDuration(10 * 365 * 24 * 60 * 60 * 1000), '10 years')
-})
-
-test('formatDuration handles singular forms correctly', (t) => {
-  t.is(formatDuration(1000), '1 second')
-  t.is(formatDuration(60 * 1000), '1 minute')
-  t.is(formatDuration(60 * 60 * 1000), '1 hour')
-  t.is(formatDuration(24 * 60 * 60 * 1000), '1 day')
-  t.is(formatDuration(7 * 24 * 60 * 60 * 1000), '1 week')
-  t.is(formatDuration(30 * 24 * 60 * 60 * 1000), '1 month')
-  t.is(formatDuration(365 * 24 * 60 * 60 * 1000), '1 year')
-})
-
-test('formatDuration handles plural forms correctly', (t) => {
-  t.is(formatDuration(2000), '2 seconds')
-  t.is(formatDuration(2 * 60 * 1000), '2 minutes')
-  t.is(formatDuration(2 * 60 * 60 * 1000), '2 hours')
-  t.is(formatDuration(2 * 24 * 60 * 60 * 1000), '2 days')
-  t.is(formatDuration(2 * 7 * 24 * 60 * 60 * 1000), '2 weeks')
-  t.is(formatDuration(2 * 30 * 24 * 60 * 60 * 1000), '2 months')
-  t.is(formatDuration(2 * 365 * 24 * 60 * 60 * 1000), '2 years')
-})
-
-test('default export is the same as named export', async (t) => {
-  const module = await import('./formatDuration.js')
-  t.is(module.default, module.formatDuration)
-})

package/src/lib/doctor/formatters/human.js

@@ -1,257 +0,0 @@
-/**
- * Human-readable formatter for doctor check results
- *
- * Formats check results for terminal display with colors and icons.
- *
- * @module lib/doctor/formatters/human
- */
-import chalk from 'chalk'
-import wrapAnsi from 'wrap-ansi'
-import {
-  STATUS_ICONS,
-  countResults,
-  filterResults,
-  getStatus,
-  getTerminalWidth
-} from './shared.js'
-
-/**
- * Log level for output routing
- * @typedef {'info'|'warn'|'error'} LogLevel
- */
-
-/**
- * Formatted line with routing information
- * @typedef {Object} FormattedLine
- * @property {string} text - The formatted text to display
- * @property {LogLevel} level - The log level for routing (info, warn, error)
- */
-
-/**
- * Wrap text to fit within the terminal, preserving indentation
- *
- * Each line in the input is indented by `indent` spaces. The text is
- * wrapped so that the total line width (indent + content) does not
- * exceed the terminal width. Continuation lines receive the same indent.
- *
- * @param {string} text - Text to wrap (may contain newlines)
- * @param {number} indent - Number of leading spaces for each line
- * @param {number} columns - Terminal width in columns
- * @returns {string} Wrapped and indented text
- */
-function wrapIndented(text, indent, columns) {
-  const prefix = ' '.repeat(indent)
-  const contentWidth = Math.max(columns - indent, 20)
-
-  return text
-    .split('\n')
-    .map((line) => {
-      const wrapped = wrapAnsi(line, contentWidth, { hard: true, trim: false })
-      return wrapped
-        .split('\n')
-        .map((wl) => `${prefix}${wl}`)
-        .join('\n')
-    })
-    .join('\n')
-}
-
-/**
- * Format a single check result for human display
- *
- * @param {Object} result - Check result
- * @param {Object} [options] - Formatting options
- * @param {boolean} [options.verbose] - Include additional details
- * @param {number} [options.columns] - Terminal width in columns
- * @returns {FormattedLine}
- */
-function formatCheck(result, options = {}) {
-  const { name, ok, level, message, details, remediation, docsUrl } = result
-  const status = getStatus(result)
-  const statusIcon = STATUS_ICONS[status]
-  const columns = options.columns || getTerminalWidth()
-
-  const statusLine = message ? `  ${statusIcon} ${name}: ${message}` : `  ${statusIcon} ${name}`
-  const lines = [statusLine]
-
-  // Show details when verbose is enabled
-  if (options.verbose && details) {
-    lines.push(wrapIndented(details, 6, columns))
-  }
-
-  // Show remediation guidance for failed/timeout checks
-  if (!ok && remediation) {
-    lines.push('')
-    lines.push(`    How to fix:`)
-    lines.push(wrapIndented(remediation, 4, columns))
-  }
-
-  if (!ok && docsUrl) {
-    lines.push('')
-    lines.push(`    Documentation: ${docsUrl}`)
-    lines.push('')
-  }
-
-  // Determine log level for routing
-  let logLevel = 'info'
-  if (!ok && level !== 'na') {
-    if (level === 'warn' || level === 'timeout') {
-      logLevel = 'warn'
-    } else {
-      logLevel = 'error'
-    }
-  }
-
-  return {
-    text: lines.join('\n'),
-    level: logLevel,
-  }
-}
-
-/**
- * Build summary text and exit code from unfiltered section counts
- *
- * @param {Array} sections - Unfiltered check results organized by section
- * @returns {{summary: FormattedLine, exitCode: number}}
- */
-function buildSummary(sections) {
-  const counts = countResults(sections)
-  const naSuffix = counts.na > 0
-    ? ` (${counts.na} not applicable)`
-    : ''
-
-  let summary
-  let exitCode = 0
-
-  if (counts.failed > 0) {
-    const errorText = counts.failed === 1 ? '1 check failed' : `${counts.failed} checks failed`
-    const extras = []
-    if (counts.warnings > 0) extras.push(counts.warnings === 1 ? '1 warning' : `${counts.warnings} warnings`)
-    if (counts.timeouts > 0) extras.push(counts.timeouts === 1 ? '1 timed out' : `${counts.timeouts} timed out`)
-    const extrasText = extras.length > 0 ? `, ${extras.join(', ')}` : ''
-    summary = { text: `${errorText}${extrasText}. See above for details.${naSuffix}`, level: 'error' }
-    exitCode = 1
-  } else if (counts.warnings > 0 || counts.timeouts > 0) {
-    const parts = []
-    if (counts.warnings > 0) parts.push(counts.warnings === 1 ? '1 warning' : `${counts.warnings} warnings`)
-    if (counts.timeouts > 0) parts.push(counts.timeouts === 1 ? '1 timed out' : `${counts.timeouts} timed out`)
-    summary = { text: `All checks passed with ${parts.join(', ')}.${naSuffix}`, level: 'warn' }
-  } else {
-    summary = { text: `All checks passed!${naSuffix}`, level: 'info' }
-  }
-
-  return { summary, exitCode }
-}
-
-/**
- * Format check results for human-readable display
- *
- * @param {Array} sections - Check results organized by section
- * @param {Object} [options] - Formatting options
- * @param {boolean} [options.errors] - Only include failed checks
- * @param {boolean} [options.warnings] - Only include warning checks
- * @param {boolean} [options.verbose] - Include additional details
- * @param {number} [options.columns] - Terminal width override (default: auto-detected)
- * @param {string} [options.label='diagnostic checks'] - Description of checks being run
- * @returns {{lines: FormattedLine[], summary: FormattedLine|null, key: FormattedLine|null, exitCode: number, isEmpty: boolean}}
- *
- * @example
- * const { lines, summary, key, exitCode } = formatHuman(sections, { verbose: true })
- * for (const { text, level } of lines) {
- *   logger[level](text)
- * }
- * if (summary) logger[summary.level](summary.text)
- */
-export function formatHuman(sections, options = {}) {
-  const { label = 'diagnostic checks', verbose = false, columns } = options
-  const terminalColumns = columns || getTerminalWidth()
-  const filteredSections = filterResults(sections, options)
-
-  const lines = []
-  let errorCount = 0
-  let warningCount = 0
-  let timeoutCount = 0
-  let naCount = 0
-  let displayedCount = 0
-
-  // Header (append filter description when active)
-  let filterSuffix = ''
-  if (options.errors && options.warnings) {
-    filterSuffix = ' (warnings and errors only)'
-  } else if (options.errors) {
-    filterSuffix = ' (errors only)'
-  } else if (options.warnings) {
-    filterSuffix = ' (warnings only)'
-  }
-  lines.push({ text: `Running ${label}${filterSuffix}...\n`, level: 'info' })
-
-  // Process each section
-  for (const { section, results } of filteredSections) {
-    // Section header
-    lines.push({ text: chalk.bold(section), level: 'info' })
-
-    for (const result of results) {
-      displayedCount++
-
-      // Count by status category
-      if (result.level === 'na') {
-        naCount++
-      } else if (!result.ok) {
-        if (result.level === 'warn') {
-          warningCount++
-        } else if (result.level === 'timeout') {
-          timeoutCount++
-        } else {
-          errorCount++
-        }
-      }
-
-      lines.push(formatCheck(result, { verbose, columns: terminalColumns }))
-    }
-
-    // Blank line between sections
-    lines.push({ text: '', level: 'info' })
-  }
-
-  // Handle case where filters excluded all results
-  if (displayedCount === 0) {
-    let emptyMessage = null
-    if (options.errors && options.warnings) {
-      emptyMessage = 'No failed checks or warnings found.'
-    } else if (options.errors) {
-      emptyMessage = 'No failed checks found.'
-    } else if (options.warnings) {
-      emptyMessage = 'No warnings found.'
-    }
-
-    // Even when the filter shows nothing, summary and exitCode reflect unfiltered status
-    const { summary, exitCode } = buildSummary(sections)
-    return {
-      lines: emptyMessage ? [{ text: emptyMessage, level: 'info' }] : [],
-      summary,
-      key: null,
-      exitCode,
-      isEmpty: true,
-    }
-  }
-
-  // Build summary from unfiltered counts so filters don't hide the overall status
-  const { summary, exitCode } = buildSummary(sections)
-
-  // Build key (hidden when filtering to --errors or --warnings only)
-  const key = (options.errors || options.warnings)
-    ? null
-    : {
-        text: `Key: ${STATUS_ICONS.passed} passed  ${STATUS_ICONS.failed} failed  ${STATUS_ICONS.warning} warning  ${STATUS_ICONS.timeout} timed out  ${STATUS_ICONS.na} not applicable / not yet generated`,
-        level: 'info',
-      }
-
-  return {
-    lines,
-    summary,
-    key,
-    exitCode,
-    isEmpty: false,
-  }
-}
-
-export default formatHuman