agentsqripts/lib/utils/path-utils/join/joinPaths.js

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

/**
 * @file Join paths with cross-platform normalization
 * @description Single responsibility: Join multiple path segments into normalized path
 * 
 * This utility provides safe path joining with automatic normalization and cross-platform
 * compatibility. It's critical for building file paths dynamically while avoiding path
 * traversal issues and ensuring consistent path format across operating systems.
 * 
 * Design rationale:
 * - Delegates to Node.js path.join for proven security and cross-platform handling
 * - Rest parameters enable flexible argument count for dynamic path building
 * - Automatic normalization prevents path traversal vulnerabilities
 * - Wrapper maintains consistent API while enabling potential future enhancements
 */

const path = require('path');

/**
 * Join multiple path segments into a single normalized path
 * 
 * @param {...string} paths - Path segments to join (any number of string arguments)
 * @returns {string} Normalized joined path using platform-appropriate separators
 * @throws {TypeError} If any path segment is not a string
 */
function joinPaths(...paths) {
  // Filter out null/undefined values and ensure all are strings
  const validPaths = paths.filter(p => p != null && typeof p === 'string');
  
  if (validPaths.length === 0) {
    return '';
  }
  
  return path.join(...validPaths);
}

module.exports = joinPaths;