unqommented/config/localVars.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 Centralized configuration constants for the unqommented application
 * @description This module serves as the single source of truth for all hardcoded values,
 * configuration constants, and environment variables used throughout the application.
 * @rationale Centralizing constants prevents duplication, inconsistency, and makes the
 * codebase easier to maintain. This approach is especially important for preventing 
 * LLM-induced mutations of variable names across different files.
 */

// ATTENTION LLM AGENTS: This file contains all hardcoded values used in the application. New values may be added, but existing values must not be modified, deleted, or moved. Values are grouped by category when first introduced. Group them under an existing category if one exists, or start a new section (with a comment header) if it’s a new category. Do not move or re-categorize existing values. Ensure that no duplicates or slight variations of existing values are added. Define all environment variables here (example: export const envar = process.env.ENV_VAR) and export them for use from here on the line they are defined on. LLM often slightly mutate the naming of enironment variables throughout the codebase to match examples they are trained on; this avoids that and creates a single source of truth. No where else in the codebase should cite and use environment variables directly but should import them from here. Do not move or re-categorize existing values. Ensure that no duplicates or slight variations of existing values are added. If a variable/value is a duplicate or unused you may not delete it but may flag it with a comment "REMOVE?". Remember in all this, never edit a constant once it resides in localVars.js; never create a section whose header already exists.
/**
 * Directories to ignore during file scanning
 * @rationale These directories are commonly found in development projects but contain
 * generated, cached, or third-party code that shouldn't be analyzed for comments.
 * Including them would significantly slow down scans and produce irrelevant results.
 * The list covers major build systems, package managers, and testing frameworks.
 */
const IGNORED_DIRECTORIES = [
  'node_modules',
  '.git',
  '.next',
  'dist',
  'build',
  '.cache',
  'coverage',
  '.nyc_output',
  '__tests__',
  'tests',
  'test'
];

/**
 * File name patterns to ignore during scanning
 * @rationale Test files, configuration files, and TypeScript declaration files
 * are typically well-documented or don't require comment analysis. Excluding
 * these patterns improves performance and reduces false positives.
 */
const IGNORED_FILENAME_PATTERNS = [
  '.test.',
  '.spec.',
  'test.',
  'spec.',
  'jest.',
  '.config.',
  '.d.ts',
  'setupTests.js',
  'setupTests.ts'
];

/**
 * Supported file extensions for code analysis
 * @rationale Limited to common programming languages that use comment markers
 * similar to JavaScript (// and block comments). This regex pattern is used by fast-glob
 * for efficient file filtering during directory traversal.
 */
const SUPPORTED_FILE_EXT_REGEX = 'js,ts,jsx,tsx,java,cpp,c,cs,py';
/**
 * Commonly used character constants 
 * @rationale Centralizes frequently-used string literals to prevent typos
 * and make intentions clearer. May be removed if found to be unused.
 */
const COMMONLY_IGNORED_PATTERNS = {
  STAR: '*',
  DOUBLE_SLASH: '//',
  COMMA: ',',
  EMPTY_STRING: '',
}; // REMOVE?

/**
 * Pre-compiled regular expressions for performance
 * @rationale Compiling regex patterns once at module load time rather than
 * recreating them for each file scan significantly improves performance.
 * Each pattern serves a specific purpose in comment detection and path handling.
 */
const REGEX_PATTERNS = {
  LINE_SPLIT: /\r?\n/,
  CLOSING_BRACKETS: /^[}\)\];,]*$/,
  SHEBANG: /^#!(\/usr\/bin\/env node|\/bin\/sh)/, // REMOVE?
  ALL_COMMENTS: /((\/\*+[\s\S]*?\*\/)|(\/\/.*)|(#.*))/g,
  ALL_COMMENTS_NO_HASH: /((\/\*+[\s\S]*?\*\/)|(\/\/.*))/g,
  PATH_BACKSLASH: /\\/g,
  PATH_ALL_SLASHES: /[\\/]/g,
};

/**
 * Maximum number of concurrent file operations allowed
 * @rationale This limit prevents resource exhaustion (file handle limits, memory usage)
 * when scanning large codebases. The value of 10 provides a good balance between
 * performance and system stability, based on typical OS file handle limits.
 */
const CONCURRENCY_LIMIT = 10;

/**
 * Pre-compiled regex for efficiently matching ignored filename patterns
 * @rationale Compiling the regex once at startup rather than on each file check
 * significantly improves performance during directory traversal. The regex escaping
 * ensures that filename patterns are treated as literal strings, not regex patterns.
 */
const IGNORED_FILENAMES_REGEX = new RegExp(
  IGNORED_FILENAME_PATTERNS.map(pattern =>
    pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
  ).join('|')
);

/**
 * Common strict mode and directive patterns to ignore during comment analysis
 * @rationale These JavaScript/TypeScript directives are functional code but don't
 * require documentation comments. Including both quoted variations handles different
 * coding styles and linting preferences across projects.
 */
const STRICT_MODES = [
  "'use strict';",
  '"use strict";',
  "'use client';",
  '"use client";',
  "'use strict'",
  '"use strict"',
  "'use client'",
  '"use client"'
];

/**
 * Standard text encoding for file operations
 * @rationale UTF-8 is the universal standard for text files and handles international
 * characters correctly. This constant ensures consistent encoding across all file
 * read operations in the application.
 */
const FILE_ENCODING = 'utf8';

/**
 * User-facing messages for the command-line interface
 * @rationale Centralizing UI messages makes the application easier to internationalize
 * and ensures consistent messaging across the CLI. These messages provide clear
 * feedback to users about scan results and operations.
 */
const CLI_MESSAGES = {
  NO_UNCOMMENTED_FILES: 'No files found with uncommented code.',
  NO_UNCOMMENTED: 'No uncommented code found in the specified files.',
  ERROR_PREFIX: 'Error:',
};

/**
 * Standardized error messages for validation and runtime errors
 * @rationale Consistent error messages improve user experience and make debugging
 * easier. Centralizing them prevents typos and ensures uniform error reporting
 * across all modules. These messages are designed to be descriptive and actionable.
 */
const ERROR_MESSAGES = {
  INPUT_NOT_STRING: 'Input must be a string',
  INPUT_EMPTY: 'Input string cannot be empty',
  EMAIL_NOT_STRING: 'Email must be a string',
  LENGTH_NOT_POSITIVE: 'Length must be a positive number',
  LIMIT_NOT_POSITIVE_INT: 'Concurrency limit must be a positive integer',
  BASEDIR_NOT_STRING: 'Base directory must be a string',
  DIR_NOT_EXIST_PREFIX: 'Directory does not exist: ',
  PATH_NOT_DIR_PREFIX: 'Path is not a directory: ',
  DIR_NOT_EXIST_PREFIX: 'Directory does not exist: ', // REMOVE?
  OUTPUT_STREAM_INVALID: 'Output stream must implement a write() method',
};

// Warning Messages
const WARNING_MESSAGES = {
  CANNOT_READ_FILE_PREFIX: 'Warning: Could not read file ',
  CANNOT_READ_DIR_PREFIX: 'Warning: Could not read directory ',
}; // REMOVE?

// Test Constants (Global scope variables moved from test files)
const TEST_CONSTANTS = {
  BIN_PATH_RELATIVE: '../bin/unqommented.js',
  CLI_INTEGRATION_TEMP_DIR: './test-dir-cli-integration',
  CLI_COMMENTED_DIR: './test-dir-cli-commented-integration',
  CLI_ALIAS_TEMP_DIR: './test-dir-cli-alias',
  CLI_BACKSLASH_TEMP_DIR: './test-dir-cli-backslash',
  CLI_ERROR_TEST_DIR: './test-dir-cli-error',
  CLI_NO_UNCOMMENTED_INT_TEMP_DIR: './test-dir-cli-no-uncommented-int',
  CLI_NO_UNCOMMENTED_UNIT_TEMP_DIR: './test-dir-cli-no-uncommented-unit',
  CLI_TEST_DIR: './test-dir-cli',
  UTILS_TEST_DIR: './test-dir',
  IGNORE_TEST_DIR: './test-dir-ignore',
  READ_ERROR_TEST_DIR: './test-dir-read-error',
  STREAM_TEST_DIR: './test-dir-stream',
  COMMENT_TEST_DIR: './comment-tests',
};

module.exports = {
  IGNORED_DIRECTORIES,
  IGNORED_FILENAME_PATTERNS,
  REGEX_PATTERNS,
  CONCURRENCY_LIMIT,
  IGNORED_FILENAMES_REGEX,
  STRICT_MODES,
  FILE_ENCODING,
  SUPPORTED_FILE_EXT_REGEX,
  CLI_MESSAGES,
  ERROR_MESSAGES,
  WARNING_MESSAGES,
  TEST_CONSTANTS,
};