unqommented/bin/unqommented.js

A Node.js utility that quickly identifies files with uncommented code in your codebase. Designed for developers who want to efficiently tell LLMs exactly which files need comments added.

#!/usr/bin/env node

/**
 * @file This script serves as the command-line interface (CLI) for the 'unqommented' tool.
 * @description It provides a CLI for scanning directories to find files with uncommented code.
 * The tool is designed to be easy to use, with sensible defaults and clear error reporting.
 *
 * @example
 * // Scan the current directory
 * npx unqommented
 *
 * @example
 * // Scan a specific directory
 * npx unqommented ./src
 */

const { findUncommentedFiles } = require('../lib/utils.js');
const localVars = require('../config/localVars');
const { qerrors } = require('qerrors'); // For structured error logging
const yargs =require('yargs/yargs');
const { hideBin } = require('yargs/helpers');

/**
 * @function main
 * @description The main execution block of the CLI tool. It uses an Immediately Invoked
 * Function Expression (IIFE) to enable async/await at the top level. This function is
 * responsible for parsing command-line arguments, running the scan, and printing the results.
 */
(async () => {
  let argv;
  try {
    // Use yargs to parse command-line arguments. This provides a robust and flexible
    // way to define and handle CLI options, including the 'directory' argument.
    // The .command() method defines the primary command, and .positional() specifies
    // the 'directory' argument, its type, and a default value.
    argv = yargs(hideBin(process.argv))
      .usage('Usage: $0 [directory] [options]')
      .command('$0 [directory]', 'Scan a directory for uncommented files', (yargs) => {
        yargs.positional('directory', {
          describe: 'The directory to scan for uncommented code',
          type: 'string',
          default: '.', // Default to the current directory if not specified
        });
      })
      .help() // Automatically generate a help message
      .argv;

    // Execute the scan and await the results. The findUncommentedFiles function
    // returns both the list of uncommented files and any errors that occurred.
    const { uncommentedFiles, errors } = await findUncommentedFiles(argv.directory);

    // Process and display the results. If no uncommented files are found, a
    // success message is shown. Otherwise, the paths of the uncommented files are printed.
    if (uncommentedFiles.length === 0) {
      console.log(localVars.CLI_MESSAGES.NO_UNCOMMENTED_FILES);
    } else {
      uncommentedFiles.forEach(f => console.log(f));
    }

    // Display any errors that were collected during the scan. This ensures that
    // file-specific issues are reported without halting the entire process.
    errors.forEach(err => {
      const fileInfo = err.file ? `${err.file}: ` : '';
      console.error(`${localVars.CLI_MESSAGES.ERROR_PREFIX} ${fileInfo}${err.error}`);
    });
  } catch (error) {
    // The catch block handles critical errors that prevent the CLI from running,
    // such as an invalid directory. It logs the error using qerrors for structured
    // logging and exits with a non-zero status code to indicate failure.
    qerrors(error, 'cli', { directory: argv?.directory || 'unknown' });
    console.error(`${localVars.CLI_MESSAGES.ERROR_PREFIX} ${error.message}`);
    process.exit(1);
  }
})();