@simplysm/core-node 13.0.99 → 14.0.1

package/src/utils/fs.ts

@@ -5,19 +5,19 @@ import { glob as globRaw, type GlobOptions, globSync as globRawSync } from "glob
 import { json, SdError } from "@simplysm/core-common";
 import "@simplysm/core-common";
 
-//#region Existence Check
+//#region 존재 여부 확인
 
 /**
- * Checks if a file or directory exists (synchronous).
- * @param targetPath - Path to check
+ * 파일 또는 디렉토리가 존재하는지 확인한다 (동기).
+ * @param targetPath - 확인할 경로
  */
 export function existsSync(targetPath: string): boolean {
   return fs.existsSync(targetPath);
 }
 
 /**
- * Checks if a file or directory exists (asynchronous).
- * @param targetPath - Path to check
+ * 파일 또는 디렉토리가 존재하는지 확인한다 (비동기).
+ * @param targetPath - 확인할 경로
  */
 export async function exists(targetPath: string): Promise<boolean> {
   try {
@@ -30,11 +30,11 @@ export async function exists(targetPath: string): Promise<boolean> {
 
 //#endregion
 
-//#region Create Directory
+//#region 디렉토리 생성
 
 /**
- * Creates a directory (recursive).
- * @param targetPath - Directory path to create
+ * 디렉토리를 생성한다 (재귀적).
+ * @param targetPath - 생성할 디렉토리 경로
  */
 export function mkdirSync(targetPath: string): void {
   try {
@@ -45,8 +45,8 @@ export function mkdirSync(targetPath: string): void {
 }
 
 /**
- * Creates a directory (recursive, asynchronous).
- * @param targetPath - Directory path to create
+ * 디렉토리를 생성한다 (재귀적, 비동기).
+ * @param targetPath - 생성할 디렉토리 경로
  */
 export async function mkdir(targetPath: string): Promise<void> {
   try {
@@ -58,12 +58,12 @@ export async function mkdir(targetPath: string): Promise<void> {
 
 //#endregion
 
-//#region Delete
+//#region 삭제
 
 /**
- * Deletes a file or directory.
- * @param targetPath - Path to delete
- * @remarks The synchronous version fails immediately without retries. Use rm for cases with potential transient errors like file locks.
+ * 파일 또는 디렉토리를 삭제한다.
+ * @param targetPath - 삭제할 경로
+ * @remarks 동기 버전은 재시도 없이 즉시 실패한다. 파일 잠금 등 일시적 오류가 발생할 수 있는 경우 rm을 사용하라.
  */
 export function rmSync(targetPath: string): void {
   try {
@@ -74,9 +74,9 @@ export function rmSync(targetPath: string): void {
 }
 
 /**
- * Deletes a file or directory (asynchronous).
- * @param targetPath - Path to delete
- * @remarks The asynchronous version retries up to 6 times (500ms interval) for transient errors like file locks.
+ * 파일 또는 디렉토리를 삭제한다 (비동기).
+ * @param targetPath - 삭제할 경로
+ * @remarks 비동기 버전은 파일 잠금 등 일시적 오류에 대해 최대 6회(500ms 간격) 재시도한다.
  */
 export async function rm(targetPath: string): Promise<void> {
   try {
@@ -93,7 +93,7 @@ export async function rm(targetPath: string): Promise<void> {
 
 //#endregion
 
-//#region Copy
+//#region 복사
 
 interface CopyEntry {
   sourcePath: string;
@@ -119,18 +119,18 @@ function collectCopyEntries(
 }
 
 /**
- * Copies a file or directory.
+ * 파일 또는 디렉토리를 복사한다.
  *
- * If sourcePath does not exist, no action is performed and the function returns.
+ * sourcePath가 존재하지 않으면 아무 작업도 수행하지 않고 반환한다.
  *
- * @param sourcePath Path of the source to copy
- * @param targetPath Destination path for the copy
- * @param filter A filter function that determines whether to copy.
- *               The **absolute path** of each file/directory is passed.
- *               Returns true to copy, false to exclude.
- *               **Note**: The top-level sourcePath is not subject to filtering;
- *               the filter function is applied recursively to all children (direct and indirect).
- *               Returning false for a directory skips that directory and all its contents.
+ * @param sourcePath 복사할 원본 경로
+ * @param targetPath 복사 대상 경로
+ * @param filter 복사 여부를 결정하는 필터 함수.
+ *               각 파일/디렉토리의 **절대 경로**가 전달된다.
+ *               true를 반환하면 복사, false를 반환하면 제외한다.
+ *               **주의**: 최상위 sourcePath는 필터링 대상이 아니며,
+ *               필터 함수는 모든 하위 항목(직접 및 간접)에 재귀적으로 적용된다.
+ *               디렉토리에 대해 false를 반환하면 해당 디렉토리와 모든 내용을 건너뛴다.
  */
 export function copySync(
   sourcePath: string,
@@ -141,12 +141,7 @@ export function copySync(
     return;
   }
 
-  let stats: fs.Stats;
-  try {
-    stats = fs.lstatSync(sourcePath);
-  } catch (err) {
-    throw new SdError(err, sourcePath);
-  }
+  const stats = lstatSync(sourcePath);
 
   if (stats.isDirectory()) {
     mkdirSync(targetPath);
@@ -166,18 +161,18 @@ export function copySync(
 }
 
 /**
- * Copies a file or directory (asynchronous).
+ * 파일 또는 디렉토리를 복사한다 (비동기).
  *
- * If sourcePath does not exist, no action is performed and the function returns.
+ * sourcePath가 존재하지 않으면 아무 작업도 수행하지 않고 반환한다.
  *
- * @param sourcePath Path of the source to copy
- * @param targetPath Destination path for the copy
- * @param filter A filter function that determines whether to copy.
- *               The **absolute path** of each file/directory is passed.
- *               Returns true to copy, false to exclude.
- *               **Note**: The top-level sourcePath is not subject to filtering;
- *               the filter function is applied recursively to all children (direct and indirect).
- *               Returning false for a directory skips that directory and all its contents.
+ * @param sourcePath 복사할 원본 경로
+ * @param targetPath 복사 대상 경로
+ * @param filter 복사 여부를 결정하는 필터 함수.
+ *               각 파일/디렉토리의 **절대 경로**가 전달된다.
+ *               true를 반환하면 복사, false를 반환하면 제외한다.
+ *               **주의**: 최상위 sourcePath는 필터링 대상이 아니며,
+ *               필터 함수는 모든 하위 항목(직접 및 간접)에 재귀적으로 적용된다.
+ *               디렉토리에 대해 false를 반환하면 해당 디렉토리와 모든 내용을 건너뛴다.
  */
 export async function copy(
   sourcePath: string,
@@ -188,12 +183,7 @@ export async function copy(
     return;
   }
 
-  let stats: fs.Stats;
-  try {
-    stats = await fs.promises.lstat(sourcePath);
-  } catch (err) {
-    throw new SdError(err, sourcePath);
-  }
+  const stats = await lstat(sourcePath);
 
   if (stats.isDirectory()) {
     await mkdir(targetPath);
@@ -215,11 +205,11 @@ export async function copy(
 
 //#endregion
 
-//#region Read File
+//#region 파일 읽기
 
 /**
- * Reads a file as a UTF-8 string.
- * @param targetPath - Path of the file to read
+ * 파일을 UTF-8 문자열로 읽는다.
+ * @param targetPath - 읽을 파일 경로
  */
 export function readSync(targetPath: string): string {
   try {
@@ -230,8 +220,8 @@ export function readSync(targetPath: string): string {
 }
 
 /**
- * Reads a file as a UTF-8 string (asynchronous).
- * @param targetPath - Path of the file to read
+ * 파일을 UTF-8 문자열로 읽는다 (비동기).
+ * @param targetPath - 읽을 파일 경로
  */
 export async function read(targetPath: string): Promise<string> {
   try {
@@ -242,8 +232,8 @@ export async function read(targetPath: string): Promise<string> {
 }
 
 /**
- * Reads a file as a Buffer.
- * @param targetPath - Path of the file to read
+ * 파일을 Buffer로 읽는다.
+ * @param targetPath - 읽을 파일 경로
  */
 export function readBufferSync(targetPath: string): Buffer {
   try {
@@ -254,8 +244,8 @@ export function readBufferSync(targetPath: string): Buffer {
 }
 
 /**
- * Reads a file as a Buffer (asynchronous).
- * @param targetPath - Path of the file to read
+ * 파일을 Buffer로 읽는다 (비동기).
+ * @param targetPath - 읽을 파일 경로
  */
 export async function readBuffer(targetPath: string): Promise<Buffer> {
   try {
@@ -266,8 +256,8 @@ export async function readBuffer(targetPath: string): Promise<Buffer> {
 }
 
 /**
- * Reads a JSON file (using JsonConvert).
- * @param targetPath - Path of the JSON file to read
+ * JSON 파일을 읽는다 (JsonConvert 사용).
+ * @param targetPath - 읽을 JSON 파일 경로
  */
 export function readJsonSync<TData = unknown>(targetPath: string): TData {
   const contents = readSync(targetPath);
@@ -280,8 +270,8 @@ export function readJsonSync<TData = unknown>(targetPath: string): TData {
 }
 
 /**
- * Reads a JSON file (using JsonConvert, asynchronous).
- * @param targetPath - Path of the JSON file to read
+ * JSON 파일을 읽는다 (JsonConvert 사용, 비동기).
+ * @param targetPath - 읽을 JSON 파일 경로
  */
 export async function readJson<TData = unknown>(targetPath: string): Promise<TData> {
   const contents = await read(targetPath);
@@ -295,12 +285,12 @@ export async function readJson<TData = unknown>(targetPath: string): Promise<TDa
 
 //#endregion
 
-//#region Write File
+//#region 파일 쓰기
 
 /**
- * Writes data to a file (auto-creates parent directories).
- * @param targetPath - Path of the file to write
- * @param data - Data to write (string or binary)
+ * 파일에 데이터를 쓴다 (상위 디렉토리 자동 생성).
+ * @param targetPath - 쓸 파일 경로
+ * @param data - 쓸 데이터 (문자열 또는 바이너리)
  */
 export function writeSync(targetPath: string, data: string | Uint8Array): void {
   mkdirSync(path.dirname(targetPath));
@@ -313,9 +303,9 @@ export function writeSync(targetPath: string, data: string | Uint8Array): void {
 }
 
 /**
- * Writes data to a file (auto-creates parent directories, asynchronous).
- * @param targetPath - Path of the file to write
- * @param data - Data to write (string or binary)
+ * 파일에 데이터를 쓴다 (상위 디렉토리 자동 생성, 비동기).
+ * @param targetPath - 쓸 파일 경로
+ * @param data - 쓸 데이터 (문자열 또는 바이너리)
  */
 export async function write(targetPath: string, data: string | Uint8Array): Promise<void> {
   await mkdir(path.dirname(targetPath));
@@ -328,10 +318,10 @@ export async function write(targetPath: string, data: string | Uint8Array): Prom
 }
 
 /**
- * Writes data to a JSON file (using JsonConvert).
- * @param targetPath - Path of the JSON file to write
- * @param data - Data to write
- * @param options - JSON serialization options
+ * JSON 파일에 데이터를 쓴다 (JsonConvert 사용).
+ * @param targetPath - 쓸 JSON 파일 경로
+ * @param data - 쓸 데이터
+ * @param options - JSON 직렬화 옵션
  */
 export function writeJsonSync(
   targetPath: string,
@@ -346,10 +336,10 @@ export function writeJsonSync(
 }
 
 /**
- * Writes data to a JSON file (using JsonConvert, asynchronous).
- * @param targetPath - Path of the JSON file to write
- * @param data - Data to write
- * @param options - JSON serialization options
+ * JSON 파일에 데이터를 쓴다 (JsonConvert 사용, 비동기).
+ * @param targetPath - 쓸 JSON 파일 경로
+ * @param data - 쓸 데이터
+ * @param options - JSON 직렬화 옵션
  */
 export async function writeJson(
   targetPath: string,
@@ -365,11 +355,11 @@ export async function writeJson(
 
 //#endregion
 
-//#region Read Directory
+//#region 디렉토리 읽기
 
 /**
- * Reads the contents of a directory.
- * @param targetPath - Path of the directory to read
+ * 디렉토리의 내용을 읽는다.
+ * @param targetPath - 읽을 디렉토리 경로
  */
 export function readdirSync(targetPath: string): string[] {
   try {
@@ -380,8 +370,8 @@ export function readdirSync(targetPath: string): string[] {
 }
 
 /**
- * Reads the contents of a directory (asynchronous).
- * @param targetPath - Path of the directory to read
+ * 디렉토리의 내용을 읽는다 (비동기).
+ * @param targetPath - 읽을 디렉토리 경로
  */
 export async function readdir(targetPath: string): Promise<string[]> {
   try {
@@ -393,11 +383,11 @@ export async function readdir(targetPath: string): Promise<string[]> {
 
 //#endregion
 
-//#region File Information
+//#region 파일 정보
 
 /**
- * Gets file/directory information (follows symbolic links).
- * @param targetPath - Path to query information for
+ * 파일/디렉토리 정보를 가져온다 (심볼릭 링크를 따라감).
+ * @param targetPath - 정보를 조회할 경로
  */
 export function statSync(targetPath: string): fs.Stats {
   try {
@@ -408,8 +398,8 @@ export function statSync(targetPath: string): fs.Stats {
 }
 
 /**
- * Gets file/directory information (follows symbolic links, asynchronous).
- * @param targetPath - Path to query information for
+ * 파일/디렉토리 정보를 가져온다 (심볼릭 링크를 따라감, 비동기).
+ * @param targetPath - 정보를 조회할 경로
  */
 export async function stat(targetPath: string): Promise<fs.Stats> {
   try {
@@ -420,8 +410,8 @@ export async function stat(targetPath: string): Promise<fs.Stats> {
 }
 
 /**
- * Gets file/directory information (does not follow symbolic links).
- * @param targetPath - Path to query information for
+ * 파일/디렉토리 정보를 가져온다 (심볼릭 링크를 따라가지 않음).
+ * @param targetPath - 정보를 조회할 경로
  */
 export function lstatSync(targetPath: string): fs.Stats {
   try {
@@ -432,8 +422,8 @@ export function lstatSync(targetPath: string): fs.Stats {
 }
 
 /**
- * Gets file/directory information (does not follow symbolic links, asynchronous).
- * @param targetPath - Path to query information for
+ * 파일/디렉토리 정보를 가져온다 (심볼릭 링크를 따라가지 않음, 비동기).
+ * @param targetPath - 정보를 조회할 경로
  */
 export async function lstat(targetPath: string): Promise<fs.Stats> {
   try {
@@ -448,10 +438,10 @@ export async function lstat(targetPath: string): Promise<fs.Stats> {
 //#region Glob
 
 /**
- * Searches for files using a glob pattern.
- * @param pattern - Glob pattern (e.g., "**\/*.ts")
- * @param options - glob options
- * @returns Array of absolute paths for matched files
+ * Glob 패턴을 사용하여 파일을 검색한다.
+ * @param pattern - Glob 패턴 (예: "**\/*.ts")
+ * @param options - glob 옵션
+ * @returns 매칭된 파일의 절대 경로 배열
  */
 export function globSync(pattern: string, options?: GlobOptions): string[] {
   return globRawSync(pattern.replace(/\\/g, "/"), options ?? {}).map((item) =>
@@ -460,10 +450,10 @@ export function globSync(pattern: string, options?: GlobOptions): string[] {
 }
 
 /**
- * Searches for files using a glob pattern (asynchronous).
- * @param pattern - Glob pattern (e.g., "**\/*.ts")
- * @param options - glob options
- * @returns Array of absolute paths for matched files
+ * Glob 패턴을 사용하여 파일을 검색한다 (비동기).
+ * @param pattern - Glob 패턴 (예: "**\/*.ts")
+ * @param options - glob 옵션
+ * @returns 매칭된 파일의 절대 경로 배열
  */
 export async function glob(pattern: string, options?: GlobOptions): Promise<string[]> {
   return (await globRaw(pattern.replace(/\\/g, "/"), options ?? {})).map((item) =>
@@ -473,11 +463,11 @@ export async function glob(pattern: string, options?: GlobOptions): Promise<stri
 
 //#endregion
 
-//#region Utilities
+//#region 유틸리티
 
 /**
- * Recursively searches and deletes empty directories under a specified directory.
- * If all child directories are deleted and a parent becomes empty, it will also be deleted.
+ * 지정된 디렉토리 하위의 빈 디렉토리를 재귀적으로 검색하여 삭제한다.
+ * 모든 하위 디렉토리가 삭제되어 상위 디렉토리가 비게 되면, 해당 디렉토리도 삭제된다.
  */
 export async function clearEmptyDirectory(dirPath: string): Promise<void> {
   if (!(await exists(dirPath))) return;
@@ -487,30 +477,31 @@ export async function clearEmptyDirectory(dirPath: string): Promise<void> {
 
   for (const childName of childNames) {
     const childPath = path.resolve(dirPath, childName);
-    if ((await lstat(childPath)).isDirectory()) {
+    const childStat = await lstat(childPath);
+    if (childStat.isDirectory()) {
       await clearEmptyDirectory(childPath);
     } else {
       hasFiles = true;
     }
   }
 
-  // If there are files, cannot delete
+  // 파일이 있으면 삭제 불가
   if (hasFiles) return;
 
-  // Only re-check if there were no files (child directories may have been deleted)
+  // 파일이 없는 경우에만 다시 확인 (하위 디렉토리가 삭제되었을 수 있음)
   if ((await readdir(dirPath)).length === 0) {
     await rm(dirPath);
   }
 }
 
 /**
- * Searches for files matching a glob pattern by traversing parent directories from a start path towards the root.
- * Collects all file paths matching the childGlob pattern in each directory.
- * @param childGlob - Glob pattern to search for in each directory
- * @param fromPath - Path to start searching from
- * @param rootPath - Path to stop searching at (if not specified, searches to filesystem root).
- *                   **Note**: fromPath must be a child path of rootPath.
- *                   Otherwise, searches to the filesystem root.
+ * 시작 경로에서 루트 방향으로 부모 디렉토리를 순회하며 glob 패턴에 매칭되는 파일을 검색한다.
+ * 각 디렉토리에서 childGlob 패턴에 매칭되는 모든 파일 경로를 수집한다.
+ * @param childGlob - 각 디렉토리에서 검색할 glob 패턴
+ * @param fromPath - 검색을 시작할 경로
+ * @param rootPath - 검색을 중단할 경로 (지정하지 않으면 파일 시스템 루트까지 검색).
+ *                   **주의**: fromPath는 rootPath의 하위 경로여야 한다.
+ *                   그렇지 않으면 파일 시스템 루트까지 검색한다.
  */
 export function findAllParentChildPathsSync(
   childGlob: string,
@@ -536,13 +527,13 @@ export function findAllParentChildPathsSync(
 }
 
 /**
- * Searches for files matching a glob pattern by traversing parent directories from a start path towards the root (asynchronous).
- * Collects all file paths matching the childGlob pattern in each directory.
- * @param childGlob - Glob pattern to search for in each directory
- * @param fromPath - Path to start searching from
- * @param rootPath - Path to stop searching at (if not specified, searches to filesystem root).
- *                   **Note**: fromPath must be a child path of rootPath.
- *                   Otherwise, searches to the filesystem root.
+ * 시작 경로에서 루트 방향으로 부모 디렉토리를 순회하며 glob 패턴에 매칭되는 파일을 검색한다 (비동기).
+ * 각 디렉토리에서 childGlob 패턴에 매칭되는 모든 파일 경로를 수집한다.
+ * @param childGlob - 각 디렉토리에서 검색할 glob 패턴
+ * @param fromPath - 검색을 시작할 경로
+ * @param rootPath - 검색을 중단할 경로 (지정하지 않으면 파일 시스템 루트까지 검색).
+ *                   **주의**: fromPath는 rootPath의 하위 경로여야 한다.
+ *                   그렇지 않으면 파일 시스템 루트까지 검색한다.
  */
 export async function findAllParentChildPaths(
   childGlob: string,

package/src/utils/path.ts

@@ -6,8 +6,8 @@ import { ArgumentError } from "@simplysm/core-common";
 const NORM = Symbol("NormPath");
 
 /**
- * Brand type representing a normalized path.
- * Can only be created through norm().
+ * 정규화된 경로를 나타내는 브랜드 타입.
+ * norm()을 통해서만 생성할 수 있다.
  */
 export type NormPath = string & {
   [NORM]: never;
@@ -15,10 +15,10 @@ export type NormPath = string & {
 
 //#endregion
 
-//#region Functions
+//#region 함수
 
 /**
- * Converts to POSIX-style path (backslash → forward slash).
+ * POSIX 스타일 경로로 변환한다 (백슬래시 → 슬래시).
  *
  * @example
  * posix("C:\\Users\\test"); // "C:/Users/test"
@@ -30,13 +30,13 @@ export function posix(...args: string[]): string {
 }
 
 /**
- * Changes the directory of a file path.
+ * 파일 경로의 디렉토리를 변경한다.
  *
  * @example
  * changeFileDirectory("/a/b/c.txt", "/a", "/x");
  * // → "/x/b/c.txt"
  *
- * @throws Error if the file is not inside fromDirectory
+ * @throws 파일이 fromDirectory 내부에 없는 경우 에러 발생
  */
 export function changeFileDirectory(
   filePath: string,
@@ -48,7 +48,7 @@ export function changeFileDirectory(
   }
 
   if (!isChildPath(filePath, fromDirectory)) {
-    throw new ArgumentError(`'${filePath}' is not inside ${fromDirectory}.`, {
+    throw new ArgumentError(`'${filePath}'은(는) ${fromDirectory} 내부에 없습니다.`, {
       filePath,
       fromDirectory,
     });
@@ -58,7 +58,7 @@ export function changeFileDirectory(
 }
 
 /**
- * Returns the filename (basename) without extension.
+ * 확장자를 제외한 파일명(basename)을 반환한다.
  *
  * @example
  * basenameWithoutExt("file.txt"); // "file"
@@ -69,27 +69,27 @@ export function basenameWithoutExt(filePath: string): string {
 }
 
 /**
- * Checks if childPath is a child path of parentPath.
- * Returns false if the paths are the same.
+ * childPath가 parentPath의 하위 경로인지 확인한다.
+ * 동일한 경로이면 false를 반환한다.
  *
- * Paths are internally normalized using `norm()` and compared using
- * platform-specific path separators (Windows: `\`, Unix: `/`).
+ * 경로는 내부적으로 `norm()`을 사용하여 정규화되며,
+ * 플랫폼별 경로 구분자(Windows: `\`, Unix: `/`)를 사용하여 비교한다.
  *
  * @example
  * isChildPath("/a/b/c", "/a/b"); // true
  * isChildPath("/a/b", "/a/b/c"); // false
- * isChildPath("/a/b", "/a/b"); // false (same path)
+ * isChildPath("/a/b", "/a/b"); // false (동일 경로)
  */
 export function isChildPath(childPath: string, parentPath: string): boolean {
   const normalizedChild = norm(childPath);
   const normalizedParent = norm(parentPath);
 
-  // Same path returns false
+  // 동일 경로는 false 반환
   if (normalizedChild === normalizedParent) {
     return false;
   }
 
-  // Check if it starts with parent path + separator
+  // 부모 경로 + 구분자로 시작하는지 확인
   const parentWithSep = normalizedParent.endsWith(path.sep)
     ? normalizedParent
     : normalizedParent + path.sep;
@@ -98,27 +98,27 @@ export function isChildPath(childPath: string, parentPath: string): boolean {
 }
 
 /**
- * Normalizes the path and returns it as NormPath.
- * Converts to absolute path and normalizes using platform-specific separators.
+ * 경로를 정규화하여 NormPath로 반환한다.
+ * 절대 경로로 변환하고 플랫폼별 구분자로 정규화한다.
  *
  * @example
  * norm("/some/path"); // NormPath
- * norm("relative", "path"); // NormPath (converted to absolute path)
+ * norm("relative", "path"); // NormPath (절대 경로로 변환됨)
  */
 export function norm(...paths: string[]): NormPath {
   return path.resolve(...paths) as NormPath;
 }
 
 /**
- * Filters files based on a list of target paths.
- * Includes files that match or are children of a target path.
+ * 대상 경로 목록을 기반으로 파일을 필터링한다.
+ * 대상 경로와 일치하거나 하위에 있는 파일을 포함한다.
  *
- * @param files - File paths to filter.
- *                **Note**: Must be absolute paths under cwd.
- *                Paths outside cwd are converted to relative paths (../) for processing.
- * @param targets - Target paths (relative to cwd, POSIX style recommended)
- * @param cwd - Current working directory (absolute path)
- * @returns If targets is empty, returns files as-is; otherwise returns only files under target paths
+ * @param files - 필터링할 파일 경로.
+ *                **주의**: cwd 하위의 절대 경로여야 한다.
+ *                cwd 외부의 경로는 상대 경로(../)로 변환되어 처리된다.
+ * @param targets - 대상 경로 (cwd 기준 상대 경로, POSIX 스타일 권장)
+ * @param cwd - 현재 작업 디렉토리 (절대 경로)
+ * @returns targets가 비어있으면 files를 그대로 반환; 그렇지 않으면 대상 경로 하위의 파일만 반환
  *
  * @example
  * const files = ["/proj/src/a.ts", "/proj/src/b.ts", "/proj/tests/c.ts"];