agentsqripts/lib/utils/path-utils/get/getBasename.js

Comprehensive static code analysis toolkit for identifying technical debt, security vulnerabilities, performance issues, and code quality problems

/**
 * @file Get base name from path with cross-platform compatibility
 * @description Single responsibility: Extract the file name portion from file paths
 * 
 * This utility provides a standardized way to extract file names from paths while
 * maintaining cross-platform compatibility. It's essential for file analysis operations
 * where only the filename (not the full path) is needed for display or comparison.
 * 
 * Design rationale:
 * - Delegates to Node.js path.basename for proven cross-platform handling
 * - Wraps native function to provide consistent API across AgentSqripts utilities
 * - Handles both Windows and Unix path separators automatically
 * - Simple wrapper maintains single responsibility while enabling future enhancements
 */

const path = require('path');

/**
 * Extract file name from path using cross-platform path handling
 * 
 * Technical function: Returns the last portion of a path, typically the filename
 * 
 * Implementation rationale:
 * - Uses Node.js path.basename for robust, tested cross-platform implementation
 * - Wrapper function provides consistent API interface for potential future enhancements
 * - Delegates platform-specific logic to well-maintained Node.js standard library
 * - No custom parsing logic reduces chance of edge case bugs
 * 
 * Cross-platform considerations:
 * - Handles Windows backslash (\) and Unix forward slash (/) separators
 * - Correctly processes UNC paths on Windows systems
 * - Manages POSIX paths consistently across operating systems
 * - Preserves file extensions and handles special characters in filenames
 * 
 * Edge cases handled by Node.js path.basename:
 * - Empty string: Returns empty string
 * - Path with trailing separator: Handles gracefully
 * - Paths with special characters: Preserves correctly
 * - Relative and absolute paths: Works consistently
 * - Root paths ('/' or 'C:\'): Returns appropriate result
 * 
 * Alternative approaches considered:
 * - Custom string parsing with lastIndexOf: Rejected for cross-platform complexity
 * - Regular expressions: Rejected as less reliable than Node.js implementation
 * - Direct usage without wrapper: Rejected to maintain consistent utility API
 * 
 * @param {string} filePath - File path (absolute or relative, any platform format)
 * @returns {string} Base filename with extension, or empty string for invalid input
 * @example
 *   getBasename('/path/to/file.js') // returns 'file.js'
 *   getBasename('C:\\Windows\\file.txt') // returns 'file.txt'
 *   getBasename('./relative/path.json') // returns 'path.json'
 */
function getBasename(filePath) {
  return path.basename(filePath);
}

module.exports = getBasename;