unqommented/lib/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 Backward compatibility layer and function aggregation module
 * @description This module implements the Compatibility Layer pattern, maintaining backward
 * compatibility after the December 2024 Single Responsibility Principle (SRP) refactoring
 * that separated monolithic functionality into specialized modules.
 * @rationale During the SRP refactoring, we broke apart lib/utils.js into specialized modules
 * but needed to maintain 100% backward compatibility for existing tests and consumers. This
 * compatibility layer allows the existing API to continue working while internally delegating
 * to the new specialized modules.
 * @architectural_decision The wrapper functions for hasUncommentedCode and findUncommentedFiles
 * are essential for test mocking to work properly. The test infrastructure mocks these functions
 * through this utils module, so direct imports from specialized modules would break existing tests.
 * @performance_note This additional abstraction layer has minimal performance impact since it's
 * just function delegation, but provides significant maintainability benefits.
 * @module utils
 */

/**
 * Import functions from specialized modules organized by Single Responsibility Principle
 * @rationale Each specialized module handles one category of functionality, improving
 * code organization and maintainability. This import structure makes dependencies clear.
 */
const { formatString, removeQuotedStrings } = require('./string-utils');
const { validateEmail } = require('./validation-utils');
const { generateId } = require('./id-utils');
const { normalizePath, validateDirectory } = require('./file-utils');
const { createLimiter } = require('./concurrency-utils');

/**
 * Import the specialized code-analyzer module for delegation
 * @rationale We import the entire module rather than destructuring functions because
 * we need to create wrapper functions that can be mocked by the test infrastructure.
 * The test suite relies on mocking functions through this utils module.
 */
const codeAnalyzer = require('./code-analyzer');

/**
 * Wrapper function for hasUncommentedCode that maintains test mockability
 * @description This wrapper enables test infrastructure to mock the function properly
 * @rationale The test suite uses jest.spyOn and other mocking techniques that rely on
 * functions being properties of this utils module. Direct imports would break mocking.
 * @param {string} filePath - Path to the file to analyze
 * @returns {Promise<boolean>} True if uncommented code is found
 */
async function hasUncommentedCode(filePath) {
  return codeAnalyzer.hasUncommentedCode(filePath);
}

/**
 * Wrapper function for findUncommentedFiles with dependency injection for testing
 * @description This wrapper maintains the existing API while enabling proper test mocking
 * @rationale By passing module.exports.hasUncommentedCode, we allow tests to mock the
 * hasUncommentedCode function through this utils module, maintaining test isolation.
 * This dependency injection pattern is crucial for the existing test architecture.
 * @param {string} baseDir - Directory to scan for uncommented files
 * @param {Stream} outputStream - Optional output stream for results
 * @returns {Promise<Object>} Object containing uncommentedFiles array and errors array
 */
async function findUncommentedFiles(baseDir, outputStream = null) {
  // Pass the utils hasUncommentedCode function to allow mocking to work properly
  return codeAnalyzer.findUncommentedFiles(baseDir, outputStream, module.exports.hasUncommentedCode);
}

/**
 * Export all functions to maintain the original public API
 * @rationale This export structure preserves the exact same interface that existed before
 * the SRP refactoring, ensuring zero breaking changes for existing consumers while
 * internally leveraging the improved modular architecture.
 */
module.exports = {
  findUncommentedFiles,
  validateDirectory,
  hasUncommentedCode,
  normalizePath,
  formatString,
  validateEmail,
  generateId,
  createLimiter,
};