cli.mjs

#!/usr/bin/env node

// ISC License
// Copyright © 2024, Chris Oakman
// https://github.com/oakmac/standard-clojure-style-js/
//
// The purpose of this file is to handle everything related to running
// Standard Clojure Style via the command line.
//
// Pure helper functions live in cli_util.js (tested via cli_util.test.js,
// also used as the reference specification for porting to Lua).

// node.js imports
import fs from 'fs-plus'
import path from 'path'
import { performance } from 'node:perf_hooks'
import process from 'process'

// npm imports
import { parseEDNString, toEDNStringFromSimpleObject } from 'edn-data'
import { globSync } from 'glob'
import yargs from 'yargs'
import { hideBin } from 'yargs/helpers'
import yocto from 'yoctocolors'

// import Standard Clojure Style
// NOTE: the line below (including the UUID) gets replaced by script/build-release.js
// script before publishing to npm
import standardClj from './lib/standard-clojure-style.js' // 7b323d1c-2984-4bd1-9304-d62d8dee9a1f

// Pure helper functions (no side effects, tested separately)
import cliUtil from './cli_util.js'

const scriptStartTime = performance.now()

// NOTE: the line below (including the UUID) gets replaced by script/build-release.js
// script before publishing to npm
const programVersion = '[dev]' // 6444ef98-c603-42ca-97e7-ebe5c60382de
const programVersionVerbose = '[dev]' // 890d2c4a-b7e1-4f3a-9c56-8a1d3e5f7b92

const defaultFileExtensions = new Set(['.clj', '.cljs', '.cljc', '.jank', '.edn'])

let logLevel = 'everything'
let atLeastOneFilePrinted = false

// this is the directory where the script is being called from
// in most cases, this will be a project root
const rootDir = process.cwd()
const defaultConfigJSONFile = path.join(rootDir, '.standard-clj.json')
const defaultConfigEDNFile = path.join(rootDir, '.standard-clj.edn')

const parseEDNOptions = {
  keywordAs: 'string',
  mapAs: 'object'
}

// =============================================================================
// Util
// =============================================================================

function setToArray (s) {
  return Array.from(s)
}

// returns the last item in an Array, or null if the Array is empty
function getLastItemInArray (a) {
  const size = a.length
  if (size === 0) {
    return null
  } else {
    return a[size - 1]
  }
}

function printToStdout (s) {
  if (logLevel !== 'quiet') {
    console.log(s)
  }
}

function printToStderr (s) {
  if (logLevel !== 'quiet') {
    console.error(s)
  }
}

function exitHappy (s) {
  if (cliUtil.isString(s)) {
    printToStdout(s)
  }
  process.exit(0)
}

function exitSad (s) {
  if (cliUtil.isString(s)) {
    printToStderr(s)
  }
  process.exit(1)
}

function formatDuration (durationMs) {
  const roundedDuration = Math.round(durationMs * 100)
  return yocto.dim('[' + (roundedDuration / 100) + 'ms]')
}

// https://stackoverflow.com/a/54565854
async function readStream (stream) {
  const chunks = []
  for await (const chunk of stream) { chunks.push(chunk) }
  return Buffer.concat(chunks).toString('utf8')
}

function alwaysTrue () {
  return true
}

function setLogLevel (level) {
  logLevel = cliUtil.normalizeLogLevel(level)
}

function printProgramInfo (opts) {
  printToStdout(yocto.bold('standard-clj ' + opts.command) + ' ' + yocto.dim(programVersion))
  printToStdout('')
}

// =============================================================================
// Config file loading
// =============================================================================

function injectConfigFile (argv) {
  let config = null

  const userPassedConfigArgument = cliUtil.isString(argv.config) && argv.config !== ''
  if (userPassedConfigArgument) {
    const isJSON = argv.config.endsWith('.json')
    const isEDN = argv.config.endsWith('.edn')

    if (isJSON) {
      try {
        config = JSON.parse(fs.readFileSync(argv.config, 'utf8'))
      } catch (e) {}
    } else if (isEDN) {
      try {
        config = parseEDNString(fs.readFileSync(argv.config, 'utf8'), parseEDNOptions)
      } catch (e) {}
    }

    // exit if they passed a config file argument, but we are unable to read it
    if (!config) {
      printToStderr('Unable to load config file: ' + argv.config)
      if (isJSON) {
        printToStderr('Maybe the file is invalid JSON?')
      } else if (isEDN) {
        printToStderr('Maybe the file is invalid EDN?')
      } else {
        printToStderr('The filename does not end in .json or .edn. That is probably wrong.')
      }
      exitSad()
    }
  } else {
    // try to load the default config file
    try {
      config = JSON.parse(fs.readFileSync(defaultConfigJSONFile, 'utf8'))
    } catch (e) {}
    try {
      config = parseEDNString(fs.readFileSync(defaultConfigEDNFile, 'utf8'), parseEDNOptions)
    } catch (e) {}
  }

  // merge config into argv using the pure function
  return cliUtil.mergeConfigIntoArgv(argv, config)
}

// =============================================================================
// File discovery
// =============================================================================

// returns a Set of files from the args passed to the "list", "check", or "fix" commands
function getFilesFromArgv (argv, cmd) {
  // remove the first item, which is the command
  argv._.shift()
  const directArgs = argv._
  const fileExtensionsSet = argv['file-ext']
  let includeFiles = []

  // process the direct arguments
  directArgs.forEach(arg => {
    let possibleFileOrDir = arg
    if (!fs.isAbsolute(arg)) {
      // if the argument is not an absolute path, assume it is relative to the
      // directory where the script is being run from
      possibleFileOrDir = path.join(rootDir, arg)
    }

    if (fs.isFileSync(possibleFileOrDir)) {
      includeFiles.push(possibleFileOrDir)
    } else if (fs.isDirectorySync(possibleFileOrDir)) {
      fs.traverseTreeSync(possibleFileOrDir, (f) => {
        const fileExt = path.extname(f)
        if (fileExtensionsSet.has(fileExt)) {
          includeFiles.push(f)
        }
        return true
      }, alwaysTrue)
    } else {
      printToStderr(yocto.bold(yocto.yellow('WARN')) + ' Could not find a file or directory at "' + arg + '"')
    }
  })

  // process the --include glob patterns
  if (cliUtil.isArray(argv.include)) {
    argv.include.forEach(includeStr => {
      const filesFromGlob = globSync(includeStr)
      includeFiles = includeFiles.concat(filesFromGlob)
    })
  }

  // load --include files via config file if the user did not pass any direct arguments
  const anyDirectArgsPassed = directArgs.length > 0
  if (!anyDirectArgsPassed && argv._optionsLoadedViaConfigFile && cliUtil.isArray(argv.includeFromConfig)) {
    argv.includeFromConfig.forEach(includeStr => {
      const filesFromGlob = globSync(includeStr)
      includeFiles = includeFiles.concat(filesFromGlob)
    })
  }

  // exclude files if necessary
  const ignoreFiles = []
  let ignorePatterns = null
  // use --ignore from CLI argument
  if (cliUtil.isArray(argv.ignore)) {
    ignorePatterns = argv.ignore
    // or from config file if present
  } else if (argv._optionsLoadedViaConfigFile && cliUtil.isArray(argv.ignoreFromConfig)) {
    ignorePatterns = argv.ignoreFromConfig
  }

  if (ignorePatterns) {
    ignorePatterns.forEach(ignoreStr => {
      let possibleFileOrDir = ignoreStr
      if (!fs.isAbsolute(ignoreStr)) {
        // if the argument is not an absolute path, assume it is relative to the
        // directory where the script is being run from
        possibleFileOrDir = path.join(rootDir, ignoreStr)
      }

      if (fs.isFileSync(possibleFileOrDir)) {
        ignoreFiles.push(possibleFileOrDir)
      } else if (fs.isDirectorySync(possibleFileOrDir)) {
        fs.traverseTreeSync(possibleFileOrDir, (f) => {
          const fileExt = path.extname(f)
          if (fileExtensionsSet.has(fileExt)) {
            ignoreFiles.push(f)
          }
          return true
        }, alwaysTrue)
      } else {
        printToStderr(yocto.bold(yocto.yellow('WARN')) + ' Could not find a file or directory to ignore at "' + ignoreStr + '"')
      }
    })
  }

  const includeFilesSet = new Set(includeFiles)
  const ignoreFileSet = new Set(ignoreFiles)

  return cliUtil.setDifference(includeFilesSet, ignoreFileSet)
}

// =============================================================================
// Format and Check
// =============================================================================

function formatFileSync (formatResult, filename) {
  const formatSingleFileStartTime = performance.now()

  let fileTxt = null
  try {
    fileTxt = fs.readFileSync(filename, 'utf8')
  } catch (e) {
    // FIXME: this should match the error format below
    printToStderr('Unable to read file: ' + filename)
    atLeastOneFilePrinted = true
    formatResult.filesWithErrors.push(filename)
    return formatResult
  }

  const result = standardClj.format(fileTxt)
  const classification = cliUtil.classifyFormatResult(fileTxt, result)

  const formatSingleFileEndTime = performance.now()
  const formatDurationMs = formatSingleFileEndTime - formatSingleFileStartTime

  if (classification.action === 'error') {
    formatResult.filesWithErrors.push(filename)
    printToStderr(yocto.red('E') + ' ' + yocto.bold(yocto.red(cliUtil.relativeFilename(filename, rootDir))) + ' - ' + classification.errorMessage + ' ' + formatDuration(formatDurationMs))
    atLeastOneFilePrinted = true
    return formatResult
  }

  if (classification.action === 'formatted') {
    fs.writeFileSync(filename, classification.outputText)
    formatResult.filesThatWereFormatted.push(filename)
    printToStdout(yocto.green('F') + ' ' + yocto.bold(cliUtil.relativeFilename(filename, rootDir)) + ' ' + formatDuration(formatDurationMs))
    atLeastOneFilePrinted = true
  } else {
    formatResult.filesThatDidNotRequireFormatting.push(filename)
    if (logLevel !== 'ignore-already-formatted') {
      printToStdout(yocto.green('✓') + ' ' + yocto.bold(cliUtil.relativeFilename(filename, rootDir)) + ' ' + formatDuration(formatDurationMs))
      atLeastOneFilePrinted = true
    }
  }

  return formatResult
}

// FIXME: write an async version of this that returns a Promise
// function formatFileAsync (filename) {}

function checkFileSync (checkResult, filename) {
  const checkStartTime = performance.now()

  let fileTxt = null
  try {
    fileTxt = fs.readFileSync(filename, 'utf8')
  } catch (e) {
    // FIXME: this should match the error format below
    printToStderr('Unable to read file: ' + filename)
    atLeastOneFilePrinted = true
    checkResult.filesWithErrors.push(filename)
    return checkResult
  }

  const result = standardClj.format(fileTxt)
  const classification = cliUtil.classifyFormatResult(fileTxt, result)

  const checkEndTime = performance.now()
  const durationMs = checkEndTime - checkStartTime

  if (classification.action === 'already-formatted') {
    if (logLevel !== 'ignore-already-formatted') {
      printToStdout(yocto.green('✓') + ' ' + yocto.bold(cliUtil.relativeFilename(filename, rootDir)) + ' ' + formatDuration(durationMs))
      atLeastOneFilePrinted = true
    }
    checkResult.filesThatDidNotRequireFormatting.push(filename)
  } else if (classification.action === 'formatted') {
    printToStderr(yocto.red('✗') + ' ' + yocto.bold(cliUtil.relativeFilename(filename, rootDir)) + ' ' + formatDuration(durationMs))
    atLeastOneFilePrinted = true
    checkResult.filesThatDidRequireFormatting.push(filename)
  } else {
    // error
    const errMsg = 'Failed to format file ' + filename + ': ' + classification.errorMessage
    printToStderr(errMsg)
    atLeastOneFilePrinted = true
    checkResult.filesWithErrors.push(filename)
  }

  return checkResult
}

// =============================================================================
// yargs commands
// =============================================================================

function processCheckCmd (argv) {
  setLogLevel(argv['log-level'])

  printProgramInfo({ command: 'check' })

  const filesToProcess = getFilesFromArgv(argv, 'check')

  if (filesToProcess.size === 0) {
    exitSad('No files were passed to the "check" command. Please pass a filename, directory, or --include glob pattern.')
  } else {
    const sortedFiles = setToArray(filesToProcess).sort()

    const initialResult = {
      filesThatDidNotRequireFormatting: [],
      filesThatDidRequireFormatting: [],
      filesWithErrors: [],
      numFilesTotal: sortedFiles.length
    }
    const checkResult = sortedFiles.reduce(checkFileSync, initialResult)
    const summary = cliUtil.buildCheckSummary(checkResult)

    const checkCommandEndTime = performance.now()
    const scriptDurationMs = checkCommandEndTime - scriptStartTime

    if (atLeastOneFilePrinted) printToStdout('')

    if (summary.allFormatted) {
      if (sortedFiles.length === 1) {
        printToStdout(yocto.green('1 file formatted with Standard Clojure Style 👍') + ' ' + formatDuration(scriptDurationMs))
      } else {
        printToStdout(yocto.green('All ' + sortedFiles.length + ' files formatted with Standard Clojure Style 👍') + ' ' + formatDuration(scriptDurationMs))
      }
    } else {
      printToStdout(yocto.green(summary.numAlreadyFormatted + ' ' + cliUtil.fileStr(summary.numAlreadyFormatted) + ' formatted with Standard Clojure Style'))
      printToStdout(yocto.red(summary.numNeedFormatting + ' ' + cliUtil.fileStr(summary.numNeedFormatting) + ' require formatting'))
      printToStdout('Checked ' + summary.total + ' ' + cliUtil.fileStr(summary.total) + '. ' + formatDuration(scriptDurationMs))
    }

    if (summary.exitCode === 0) {
      exitHappy()
    } else {
      exitSad()
    }
  }
}

// this is the fix command when not reading input from stdin
function processFixCmdNotStdin (argv) {
  setLogLevel(argv['log-level'])

  printProgramInfo({ command: 'fix' })

  const filesToProcess = getFilesFromArgv(argv, 'fix')

  if (filesToProcess.size === 0) {
    exitSad('No files were passed to the "fix" command. Please pass a filename, directory, or --include glob pattern.')
  } else {
    const sortedFiles = setToArray(filesToProcess).sort()

    const initialResult = {
      filesThatDidNotRequireFormatting: [],
      filesThatWereFormatted: [],
      filesWithErrors: [],
      numFilesTotal: sortedFiles.length
    }
    const formatResult = sortedFiles.reduce(formatFileSync, initialResult)
    const summary = cliUtil.buildFixSummary(formatResult)

    const formatCommandEndTime = performance.now()
    const scriptDurationMs = formatCommandEndTime - scriptStartTime

    if (atLeastOneFilePrinted) printToStdout('')

    if (summary.allSuccess) {
      if (sortedFiles.length === 1) {
        printToStdout(yocto.green('1 file formatted with Standard Clojure Style 👍') + ' ' + formatDuration(scriptDurationMs))
      } else {
        printToStdout(yocto.green('All ' + sortedFiles.length + ' files formatted with Standard Clojure Style 👍') + ' ' + formatDuration(scriptDurationMs))
      }
    } else {
      printToStdout(yocto.green(summary.numAlreadyFormatted + summary.numWereFormatted + ' files formatted with Standard Clojure Style'))
      printToStdout(yocto.red(summary.numErrors + ' files with errors'))
      printToStdout('Checked ' + sortedFiles.length + ' files. ' + formatDuration(scriptDurationMs))
    }

    if (summary.exitCode === 0) {
      exitHappy()
    } else {
      exitSad()
    }
  }
}

// fix command when reading input from stdin
async function processFixCmdStdin (argv) {
  const stdinStr = await readStream(process.stdin)

  if (!cliUtil.isString(stdinStr) || stdinStr === '') {
    exitSad('Nothing found on stdin. Please pipe some Clojure code to stdin when using "standard-clj fix -"')
  } else {
    let formatResult = null
    try {
      formatResult = standardClj.format(stdinStr)
    } catch (e) {}

    if (formatResult && formatResult.status === 'success') {
      console.log(formatResult.out)
      exitHappy()
    } else if (formatResult && formatResult.status === 'error' && cliUtil.isString(formatResult.reason)) {
      exitSad('Failed to format code: ' + formatResult.reason)
    } else {
      exitSad('Failed to format your code due to unknown error with the format() function. Please help the standard-clj project by opening an issue to report this 🙏')
    }
  }
}

function processFixCmd (argv) {
  const lastArg = getLastItemInArray(argv._)
  if (lastArg === '-') {
    processFixCmdStdin(argv)
  } else {
    processFixCmdNotStdin(argv)
  }
}

function processListCmd (argv) {
  const filesSet = getFilesFromArgv(argv, 'list')
  const sortedFiles = setToArray(filesSet).sort()

  if (argv.output === 'json') {
    printToStdout(JSON.stringify(sortedFiles))
  } else if (argv.output === 'json-pretty') {
    printToStdout(JSON.stringify(sortedFiles, null, 2))
  } else if (argv.output === 'edn') {
    printToStdout(toEDNStringFromSimpleObject(sortedFiles))
  } else if (argv.output === 'edn-pretty') {
    // NOTE: this is hacky, but it works 🤷‍♂️
    const jsonOutput = JSON.stringify(sortedFiles)
    printToStdout(jsonOutput.replaceAll(/","/g, '"\n "'))
  } else {
    sortedFiles.forEach(printToStdout)
  }

  exitHappy()
}

// =============================================================================
// yargs setup
// =============================================================================

const yargsCheckCommand = {
  command: 'check',
  describe: 'Checks if files are formatted according to Standard Clojure Style. ' +
            'This command does not modify files. ' +
            'Returns exit code 0 if all files are formatted, 1 otherwise.',
  handler: processCheckCmd
}

const yargsFixCommand = {
  command: 'fix',
  describe: 'Formats files according to Standard Clojure Style. ' +
            'This command will modify your files on disk. ' +
            'Returns exit code 0 if all files are formatted, 1 otherwise.',
  handler: processFixCmd
}

const yargsListCommand = {
  command: 'list',
  describe: 'Prints a list of files that will be used by the "check" or "fix" commands. ' +
            'Useful for debugging your .standard-clj.edn file or glob patterns.',
  handler: processListCmd
}

yargs(hideBin(process.argv))
  .scriptName('standard-clj')
  .usage('$0 <cmd> [args]')

  .command(yargsCheckCommand)
  .command(yargsFixCommand)
  .command(yargsListCommand)

  .middleware([injectConfigFile, cliUtil.convertStringsToArrays, cliUtil.convertFileExt])

  .alias('c', 'config')
  .alias('ig', 'ignore')
  .alias('in', 'include')
  .alias('l', 'log-level')
  .alias('v', 'version')
  .alias('h', 'help')

  .default('file-ext', defaultFileExtensions)

  .demandCommand() // show them --help if they do not pass a valid command
  .version(programVersionVerbose)

  .example([
    ['$0 list src/', 'List files that will be formatted in the src/ directory (recursive)'],
    ['$0 check src/', 'Check if files are already formatted in src/'],
    ['$0 fix src/', 'Format all files in src/'],
    ['$0 fix -', 'Reads from stdin, prints a formatted file to stdout']
  ])

  .describe('l', 'Set the logging level: "everything", "ignore-already-formatted", "quiet"')

  .epilogue('For more information, see the README at https://github.com/oakmac/standard-clojure-style-js')

  .wrap(100)
  .help()
  .parse()