unqommented/lib/string-utils.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.

/**
 * @file String manipulation utilities
 * @description Provides functions for string formatting and processing
 * @module string-utils
 */

const _ = require('lodash');
const localVars = require('../config/localVars');

/**
 * @function formatString
 * @description Formats a string by capitalizing the first letter and trimming whitespace.
 * @rationale This function is designed to standardize string inputs, which is crucial for
 * maintaining data consistency, especially when dealing with user-provided data.
 * @param {string} input - The string to format.
 * @returns {string} The formatted string.
 * @throws {Error} If the input is not a string or is empty.
 */
function formatString(input) {
  // Type validation ensures that the function operates on the expected data type.
  if (typeof input !== 'string') {
    throw new Error(localVars.ERROR_MESSAGES.INPUT_NOT_STRING);
  }
  // Check for empty strings after trimming to handle whitespace-only inputs.
  if (input.trim().length === 0) {
    throw new Error(localVars.ERROR_MESSAGES.INPUT_EMPTY);
  }
  // Use lodash for robust capitalization and trimming.
  return _.capitalize(input.trim());
}

/**
 * @function removeQuotedStrings
 * @description Removes quoted strings from a line of code.
 * @rationale This is a key utility for accurately detecting comments. It prevents the code
 * from misinterpreting comment markers (e.g., `//`, `/*`) that appear inside of string literals.
 * @scalability While effective, this regex can be CPU-intensive on files with extremely long
 * lines. This is a trade-off for improved accuracy in comment detection.
 * @param {string} text - The line of code to sanitize.
 * @returns {string} The line of code without quoted strings.
 */
function removeQuotedStrings(text) {
  // This regex matches single, double, or backtick-quoted strings, handling escaped characters.
  return text.replace(/(["'`])(?:\\.|(?!\1)[^\\])*?\1/g, '');
}

module.exports = {
  formatString,
  removeQuotedStrings,
};