@simplysm/sd-cli 14.0.10 → 14.0.12

package/src/utils/replace-deps.ts

@@ -7,12 +7,12 @@ import { exec } from "child_process";
 import { promisify } from "util";
 
 /**
- * Match glob patterns from replaceDeps config with target package list
- * and return { targetName, sourcePath } pairs
+ * replaceDeps 설정의 glob 패턴을 대상 패키지 목록과 매칭하여
+ * { targetName, sourcePath } 쌍을 반환한다.
  *
- * @param replaceDeps - replaceDeps config from sd.config.ts (key: glob pattern, value: source path)
- * @param targetNames - List of package names found in node_modules (e.g., ["@simplysm/solid", ...])
- * @returns Array of matched { targetName, sourcePath }
+ * @param replaceDeps - sd.config.ts의 replaceDeps 설정 (키: glob 패턴, 값: 소스 경로)
+ * @param targetNames - node_modules에서 찾은 패키지명 목록 (예: ["@simplysm/solid", ...])
+ * @returns 매칭된 { targetName, sourcePath } 배열
  */
 export function resolveReplaceDepEntries(
   replaceDeps: Record<string, string>,
@@ -21,7 +21,7 @@ export function resolveReplaceDepEntries(
   const results: Array<{ targetName: string; sourcePath: string }> = [];
 
   for (const [pattern, sourceTemplate] of Object.entries(replaceDeps)) {
-    // Convert glob pattern to regex: * → (.*), . → \., / → [\\/]
+    // glob 패턴을 정규식으로 변환: * → (.*), . → \., / → [\\/]
     const regexpText = pattern.replace(/[\\/.+*]/g, (ch) => {
       if (ch === "*") return "(.*)";
       if (ch === ".") return "\\.";
@@ -36,7 +36,7 @@ export function resolveReplaceDepEntries(
       const match = regex.exec(targetName);
       if (match == null) continue;
 
-      // If capture group exists, substitute * in source path with captured value
+      // 캡처 그룹이 있으면 소스 경로의 *를 캡처된 값으로 치환
       const sourcePath = hasWildcard ? sourceTemplate.replace(/\*/g, match[1]) : sourceTemplate;
 
       results.push({ targetName, sourcePath });
@@ -47,11 +47,11 @@ export function resolveReplaceDepEntries(
 }
 
 /**
- * Parse pnpm-workspace.yaml content and return array of workspace packages globs
- * Simple line parsing without separate YAML library
+ * pnpm-workspace.yaml 내용을 파싱하여 워크스페이스 패키지 glob 배열을 반환한다.
+ * 별도 YAML 라이브러리 없이 간단한 줄 파싱으로 처리한다.
  *
- * @param content - Content of pnpm-workspace.yaml file
- * @returns Array of glob patterns (e.g., ["packages/*", "tools/*"])
+ * @param content - pnpm-workspace.yaml 파일 내용
+ * @returns glob 패턴 배열 (예: ["packages/*", "tools/*"])
  */
 export function parseWorkspaceGlobs(content: string): string[] {
   const lines = content.split("\n");
@@ -66,7 +66,7 @@ export function parseWorkspaceGlobs(content: string): string[] {
       continue;
     }
 
-    // List items in packages section
+    // packages 섹션의 목록 항목
     if (inPackages && trimmed.startsWith("- ")) {
       const value = trimmed
         .slice(2)
@@ -76,7 +76,7 @@ export function parseWorkspaceGlobs(content: string): string[] {
       continue;
     }
 
-    // End when other section starts
+    // 다른 섹션이 시작되면 종료
     if (inPackages && trimmed !== "" && !trimmed.startsWith("#")) {
       break;
     }
@@ -86,16 +86,16 @@ export function parseWorkspaceGlobs(content: string): string[] {
 }
 
 /**
- * Names to exclude during copy
+ * 복사 시 제외할 이름 목록
  */
 const EXCLUDED_NAMES = new Set(["node_modules", "package.json", ".cache", "tests"]);
 
 /**
- * Filter function for replaceDeps copy
- * Excludes node_modules, package.json, .cache, tests
+ * replaceDeps 복사용 필터 함수
+ * node_modules, package.json, .cache, tests를 제외한다.
  *
- * @param itemPath - Absolute path of item to copy
- * @returns true if copy target, false if excluded
+ * @param itemPath - 복사할 항목의 절대 경로
+ * @returns 복사 대상이면 true, 제외 대상이면 false
  */
 function replaceDepsCopyFilter(itemPath: string): boolean {
   const basename = path.basename(itemPath);
@@ -103,7 +103,7 @@ function replaceDepsCopyFilter(itemPath: string): boolean {
 }
 
 /**
- * replaceDeps copy/replace item
+ * replaceDeps 복사/교체 항목
  */
 export interface ReplaceDepEntry {
   targetName: string;
@@ -114,7 +114,7 @@ export interface ReplaceDepEntry {
 }
 
 /**
- * Return type of watchReplaceDeps
+ * watchReplaceDeps의 반환 타입
  */
 export interface WatchReplaceDepResult {
   entries: ReplaceDepEntry[];
@@ -122,13 +122,13 @@ export interface WatchReplaceDepResult {
 }
 
 /**
- * Collect project root and workspace package paths.
+ * 프로젝트 루트 및 워크스페이스 패키지 경로를 수집한다.
  *
- * Parse pnpm-workspace.yaml to collect absolute paths of workspace packages.
- * If file is missing or parsing fails, return only root path.
+ * pnpm-workspace.yaml을 파싱하여 워크스페이스 패키지의 절대 경로를 수집한다.
+ * 파일이 없거나 파싱 실패 시 루트 경로만 반환한다.
  *
- * @param projectRoot - Project root path
- * @returns [root, ...workspace package paths] array
+ * @param projectRoot - 프로젝트 루트 경로
+ * @returns [루트, ...워크스페이스 패키지 경로] 배열
  */
 async function collectSearchRoots(projectRoot: string): Promise<string[]> {
   const searchRoots = [projectRoot];
@@ -143,23 +143,23 @@ async function collectSearchRoots(projectRoot: string): Promise<string[]> {
       searchRoots.push(...dirs);
     }
   } catch {
-    // If pnpm-workspace.yaml doesn't exist, only process root
+    // pnpm-workspace.yaml이 존재하지 않으면 루트만 처리
   }
 
   return searchRoots;
 }
 
 /**
- * Resolve all replacement target items from replaceDeps config.
+ * replaceDeps 설정에서 모든 교체 대상 항목을 해결한다.
  *
- * 1. Parse pnpm-workspace.yaml → workspace package paths
- * 2. Find matching packages in [root, ...workspace packages] node_modules
- * 3. Pattern matching + verify source path exists + resolve symlinks
+ * 1. pnpm-workspace.yaml 파싱 → 워크스페이스 패키지 경로
+ * 2. [루트, ...워크스페이스 패키지] node_modules에서 매칭 패키지 탐색
+ * 3. 패턴 매칭 + 소스 경로 존재 확인 + symlink 해결
  *
- * @param projectRoot - Project root path
- * @param replaceDeps - replaceDeps config from sd.config.ts
- * @param logger - consola logger
- * @returns Array of resolved replacement target items
+ * @param projectRoot - 프로젝트 루트 경로
+ * @param replaceDeps - sd.config.ts의 replaceDeps 설정
+ * @param logger - consola 로거
+ * @returns 해결된 교체 대상 항목 배열
  */
 async function resolveAllReplaceDepEntries(
   projectRoot: string,
@@ -167,35 +167,47 @@ async function resolveAllReplaceDepEntries(
   logger: ReturnType<typeof consola.withTag>,
 ): Promise<ReplaceDepEntry[]> {
   const entries: ReplaceDepEntry[] = [];
+  const searchedDirs = new Set<string>();
 
+  // 초기 탐색 대상: 프로젝트 루트 + workspace 패키지들의 node_modules
   const searchRoots = await collectSearchRoots(projectRoot);
+  const pendingDirs: string[] = searchRoots.map((root) =>
+    pathx.posix(path.join(root, "node_modules")),
+  );
 
-  for (const searchRoot of searchRoots) {
-    const nodeModulesDir = pathx.posix(path.join(searchRoot, "node_modules"));
+  // 교체된 패키지의 node_modules도 재귀적으로 탐색 (간접 의존성 교체)
+  while (pendingDirs.length > 0) {
+    const nodeModulesDir = pendingDirs.pop()!;
+
+    if (searchedDirs.has(nodeModulesDir)) continue;
+    searchedDirs.add(nodeModulesDir);
 
     try {
       await fs.promises.access(nodeModulesDir);
     } catch {
-      continue; // Skip if node_modules doesn't exist
+      logger.debug(`[replace-deps] 접근 불가: ${nodeModulesDir}`);
+      continue;
     }
 
-    // Search node_modules directories using each glob pattern from replaceDeps
+    // replaceDeps의 각 glob 패턴으로 node_modules 디렉토리 탐색
     const targetNames: string[] = [];
     for (const pattern of Object.keys(replaceDeps)) {
       const matches = await glob(pattern, { cwd: nodeModulesDir });
       targetNames.push(...matches);
     }
 
+    logger.debug(`[replace-deps] 탐색: ${nodeModulesDir} → ${targetNames.length}개 매칭 (${targetNames.join(", ")})`);
+
     if (targetNames.length === 0) continue;
 
-    // Pattern matching and path resolution
+    // 패턴 매칭 및 경로 해결
     const matchedEntries = resolveReplaceDepEntries(replaceDeps, targetNames);
 
     for (const { targetName, sourcePath } of matchedEntries) {
       const targetPath = pathx.posix(path.join(nodeModulesDir, targetName));
       const resolvedSourcePath = pathx.posixResolve(projectRoot, sourcePath);
 
-      // Verify source path exists
+      // 소스 경로 존재 확인
       try {
         await fs.promises.access(resolvedSourcePath);
       } catch {
@@ -203,7 +215,7 @@ async function resolveAllReplaceDepEntries(
         continue;
       }
 
-      // If targetPath is symlink, resolve to get actual .pnpm store path
+      // targetPath가 symlink이면 실제 .pnpm 저장소 경로로 해결
       let actualTargetPath = targetPath;
       try {
         const stat = await fs.promises.lstat(targetPath);
@@ -211,9 +223,12 @@ async function resolveAllReplaceDepEntries(
           actualTargetPath = pathx.posix(await fs.promises.realpath(targetPath));
         }
       } catch {
-        // If targetPath doesn't exist, use as-is
+        // targetPath가 존재하지 않으면 그대로 사용
       }
 
+      // 동일 actualTargetPath가 이미 등록된 경우 건너뜀 (pnpm 중복 방지)
+      if (entries.some((e) => e.actualTargetPath === actualTargetPath)) continue;
+
       entries.push({
         targetName,
         sourcePath,
@@ -221,6 +236,13 @@ async function resolveAllReplaceDepEntries(
         resolvedSourcePath,
         actualTargetPath,
       });
+
+      // 교체된 패키지의 node_modules를 탐색 대기열에 추가
+      const depth = targetName.split(/[/\\]/).length;
+      const entryNodeModulesDir = pathx.posix(
+        path.resolve(actualTargetPath, ...Array(depth).fill("..")),
+      );
+      pendingDirs.push(entryNodeModulesDir);
     }
   }
 
@@ -228,14 +250,14 @@ async function resolveAllReplaceDepEntries(
 }
 
 /**
- * Replace packages in node_modules with source directories according to replaceDeps config.
+ * replaceDeps 설정에 따라 node_modules의 패키지를 소스 디렉토리로 교체한다.
  *
- * 1. Parse pnpm-workspace.yaml → workspace package paths
- * 2. Find matching packages in [root, ...workspace packages] node_modules
- * 3. Remove existing symlinks/directories → copy source path (excluding node_modules, package.json, .cache, tests)
+ * 1. pnpm-workspace.yaml 파싱 → 워크스페이스 패키지 경로
+ * 2. [루트, ...워크스페이스 패키지] node_modules에서 매칭 패키지 탐색
+ * 3. 기존 symlink/디렉토리 제거 → 소스 경로 복사 (node_modules, package.json, .cache, tests 제외)
  *
- * @param projectRoot - Project root path
- * @param replaceDeps - replaceDeps config from sd.config.ts
+ * @param projectRoot - 프로젝트 루트 경로
+ * @param replaceDeps - sd.config.ts의 replaceDeps 설정
  */
 export async function setupReplaceDeps(
   projectRoot: string,
@@ -250,7 +272,7 @@ export async function setupReplaceDeps(
 
   for (const { targetName, resolvedSourcePath, actualTargetPath } of entries) {
     try {
-      // Overwrite-copy source files to actualTargetPath (maintain existing directory, preserve symlinks)
+      // 소스 파일을 actualTargetPath에 덮어쓰기 복사 (기존 디렉토리 유지, symlink 보존)
       await fsx.copy(resolvedSourcePath, actualTargetPath, replaceDepsCopyFilter);
 
       setupCount += 1;
@@ -261,7 +283,7 @@ export async function setupReplaceDeps(
 
   logger.success(`replace-deps 설정 완료 (${setupCount}개 의존성 교체)`);
 
-  // Run postinstall scripts from replaced packages
+  // 교체된 패키지의 postinstall 스크립트 실행
   for (const { targetName, resolvedSourcePath, actualTargetPath } of entries) {
     const sourcePkgJsonPath = pathx.posix(path.join(resolvedSourcePath, "package.json"));
     try {
@@ -282,16 +304,16 @@ export async function setupReplaceDeps(
 }
 
 /**
- * Watch source directories according to replaceDeps config and copy changes to target paths.
+ * replaceDeps 설정에 따라 소스 디렉토리를 감시하고 변경사항을 대상 경로에 복사한다.
  *
- * 1. Parse pnpm-workspace.yaml → workspace package paths
- * 2. Find matching packages in [root, ...workspace packages] node_modules
- * 3. Watch source directories with FsWatcher (300ms delay)
- * 4. Copy changes to target paths (excluding node_modules, package.json, .cache, tests)
+ * 1. pnpm-workspace.yaml 파싱 → 워크스페이스 패키지 경로
+ * 2. [루트, ...워크스페이스 패키지] node_modules에서 매칭 패키지 탐색
+ * 3. FsWatcher로 소스 디렉토리 감시 (300ms 딜레이)
+ * 4. 변경사항을 대상 경로에 복사 (node_modules, package.json, .cache, tests 제외)
  *
- * @param projectRoot - Project root path
- * @param replaceDeps - replaceDeps config from sd.config.ts
- * @returns entries and dispose function
+ * @param projectRoot - 프로젝트 루트 경로
+ * @param replaceDeps - sd.config.ts의 replaceDeps 설정
+ * @returns entries 및 dispose 함수
  */
 export async function watchReplaceDeps(
   projectRoot: string,
@@ -301,7 +323,7 @@ export async function watchReplaceDeps(
 
   const entries = await resolveAllReplaceDepEntries(projectRoot, replaceDeps, logger);
 
-  // Setup source directory watchers
+  // 소스 디렉토리 감시자 설정
   const watchers: FsWatcher[] = [];
   const watchedSources = new Set<string>();
 
@@ -315,10 +337,13 @@ export async function watchReplaceDeps(
       pathx.posix(path.join(entry.resolvedSourcePath, name)),
     );
 
-    const watcher = await FsWatcher.watch([entry.resolvedSourcePath], { followSymlinks: false });
+    const watcher = await FsWatcher.watch([entry.resolvedSourcePath], {
+      followSymlinks: false,
+      ignored: [...EXCLUDED_NAMES].map((name) => `**/${name}`),
+    });
     watcher.onChange({ delay: 300 }, async (changeInfos) => {
       for (const { path: changedPath } of changeInfos) {
-        // Filter excluded items: basename match or path within excluded directory
+        // 제외 항목 필터: basename 매칭 또는 제외 디렉토리 내 경로
         if (
           EXCLUDED_NAMES.has(path.basename(changedPath)) ||
           excludedPaths.some((ep) => pathx.isChildPath(changedPath, ep))
@@ -326,26 +351,26 @@ export async function watchReplaceDeps(
           continue;
         }
 
-        // Copy for all entries using this source path
+        // 이 소스 경로를 사용하는 모든 항목에 대해 복사
         for (const e of entries) {
           if (e.resolvedSourcePath !== entry.resolvedSourcePath) continue;
 
-          // Calculate relative path from source
+          // 소스로부터의 상대 경로 계산
           const relativePath = pathx.posix(path.relative(e.resolvedSourcePath, changedPath));
           const destPath = pathx.posix(path.join(e.actualTargetPath, relativePath));
 
           try {
-            // Check if source exists
+            // 소스 존재 여부 확인
             let sourceExists = false;
             try {
               await fs.promises.access(changedPath);
               sourceExists = true;
             } catch {
-              // Source was deleted
+              // 소스가 삭제됨
             }
 
             if (sourceExists) {
-              // Check if source is directory or file
+              // 소스가 디렉토리인지 파일인지 확인
               const stat = await fs.promises.stat(changedPath);
               if (stat.isDirectory()) {
                 await fsx.mkdir(destPath);
@@ -354,7 +379,7 @@ export async function watchReplaceDeps(
                 await fsx.copy(changedPath, destPath, replaceDepsCopyFilter);
               }
             } else {
-              // Source was deleted → delete target
+              // 소스가 삭제됨 → 대상도 삭제
               await fsx.rm(destPath);
             }
           } catch (err) {

package/src/utils/sd-config.ts

@@ -7,9 +7,9 @@ import type { SdConfig, SdConfigParams } from "../sd-config.types";
 const logger = consola.withTag("sd:cli:sd-config");
 
 /**
- * Load sd.config.ts
- * @returns SdConfig object
- * @throws if sd.config.ts is missing or format is incorrect
+ * sd.config.ts를 로드한다.
+ * @returns SdConfig 객체
+ * @throws sd.config.ts가 없거나 형식이 잘못된 경우
  */
 export async function loadSdConfig(params: SdConfigParams): Promise<SdConfig> {
   const sdConfigPath = pathx.posixResolve(params.cwd, "sd.config.ts");

package/src/utils/tsc-build.ts

@@ -17,23 +17,23 @@ import { createOutputPathRewriter, addJsExtensionToImports } from "./output-path
 import { isWorkspaceDiagnostic, formatDiagnosticError } from "./diagnostic-utils";
 
 /**
- * Options for package-mode tsc build
+ * 패키지 모드 tsc 빌드 옵션
  */
 export interface TscPackageBuildOptions {
   pkgDir: string;
   cwd: string;
-  /** Output control flags: which files to emit */
+  /** 출력 제어 플래그: emit할 파일 종류 */
   output: { js: boolean; dts: boolean };
-  /** Pre-parsed tsconfig. If provided, skips parseTsconfig() call. */
+  /** 미리 파싱된 tsconfig. 제공 시 parseTsconfig() 호출을 스킵한다. */
   parsedConfig?: ts.ParsedCommandLine;
-  /** Typecheck environment. When set, adjusts compilerOptions via getCompilerOptionsForEnv(). */
+  /** 타입체크 환경. 설정 시 getCompilerOptionsForEnv()로 compilerOptions를 조정한다. */
   env?: TypecheckEnv;
-  /** Include tests/ files in typecheck-only mode. Defaults to false. */
+  /** 타입체크 전용 모드에서 tests/ 파일 포함 여부. 기본값 false. */
   includeTests?: boolean;
 }
 
 /**
- * Result of package-mode tsc build
+ * 패키지 모드 tsc 빌드 결과
  */
 export interface TscPackageBuildResult {
   success: boolean;
@@ -41,20 +41,20 @@ export interface TscPackageBuildResult {
   diagnostics: SerializedDiagnostic[];
   errorCount: number;
   warningCount: number;
-  /** ts.Program exposed for lint-with-program integration */
+  /** lint-with-program 통합을 위해 노출된 ts.Program */
   program?: ts.Program;
-  /** Files affected in this build (normalized forward-slash paths).
-   *  Used for incremental lint in watch mode. */
+  /** 이 빌드에서 영향받은 파일 (정규화된 순방향 슬래시 경로).
+   *  watch 모드에서 증분 lint에 사용한다. */
   affectedFiles?: ReadonlySet<string>;
 }
 
 /**
- * Run TypeScript incremental build for a package.
+ * 패키지에 대해 TypeScript 증분 빌드를 실행한다.
  *
- * - output.js || output.dts: emit mode (src files only, generates output files)
- * - neither: typecheck only (src files only by default, src + test files when includeTests=true)
+ * - output.js || output.dts: emit 모드 (src 파일만, 출력 파일 생성)
+ * - 둘 다 아님: 타입체크만 (기본 src 파일만, includeTests=true이면 src + test 파일)
  *
- * Uses tsBuildInfoFile for incremental compilation across runs.
+ * 실행 간 증분 컴파일을 위해 tsBuildInfoFile을 사용한다.
  */
 export function runTscPackageBuild(options: TscPackageBuildOptions): TscPackageBuildResult {
   try {
@@ -144,9 +144,9 @@ export function runTscPackageBuild(options: TscPackageBuildOptions): TscPackageB
       host,
     );
 
-    // Track affected files via builder program's incremental analysis.
-    // getSemanticDiagnosticsOfNextAffectedFile iterates files that changed since the last build.
-    // affected can be ts.SourceFile or ts.Program (when global scope changes).
+    // builder program의 증분 분석을 통해 affected 파일을 추적한다.
+    // getSemanticDiagnosticsOfNextAffectedFile은 마지막 빌드 이후 변경된 파일을 순회한다.
+    // affected는 ts.SourceFile 또는 ts.Program(전역 스코프 변경 시)일 수 있다.
     let affectedFiles: Set<string> | undefined = new Set<string>();
 
     while (true) {
@@ -155,7 +155,7 @@ export function runTscPackageBuild(options: TscPackageBuildOptions): TscPackageB
       if ("fileName" in result.affected) {
         affectedFiles?.add(pathx.posix(result.affected.fileName));
       } else {
-        // ts.Program returned — global change, treat as full rebuild
+        // ts.Program 반환 — 전역 변경, 전체 재빌드로 처리
         affectedFiles = undefined;
       }
     }
@@ -173,7 +173,7 @@ export function runTscPackageBuild(options: TscPackageBuildOptions): TscPackageB
       ...emitResult.diagnostics,
     ];
 
-    // Workspace scope: exclude node_modules, keep all workspace diagnostics
+    // 워크스페이스 범위: node_modules 제외, 모든 워크스페이스 진단 유지
     const filteredDiagnostics = allDiagnostics.filter(
       (d) => isWorkspaceDiagnostic(d, options.cwd),
     );

package/src/utils/tsconfig.ts

@@ -13,7 +13,7 @@ export type TypecheckEnv = "node" | "browser";
 const DOM_LIB_PATTERNS = ["dom", "webworker"] as const;
 
 /**
- * Extract @types/* package names from package.json devDependencies.
+ * package.json devDependencies에서 @types/* 패키지명을 추출한다.
  */
 export function getTypesFromPackageJson(packageDir: string): string[] {
   const packageJsonPath = path.join(packageDir, "package.json");
@@ -33,10 +33,10 @@ export function getTypesFromPackageJson(packageDir: string): string[] {
 }
 
 /**
- * Adjust compilerOptions for the given typecheck environment.
+ * 지정된 타입체크 환경에 맞게 compilerOptions를 조정한다.
  *
- * - node env: remove browser-related libs (dom, webworker patterns). types unchanged.
- * - browser env: lib unchanged. types set explicitly from devDeps minus "node".
+ * - node 환경: 브라우저 관련 lib(dom, webworker 패턴)을 제거한다. types는 변경 없음.
+ * - browser 환경: lib은 변경 없음. types를 devDeps에서 "node"를 제외하고 명시적으로 설정한다.
  */
 export function getCompilerOptionsForEnv(
   baseOptions: ts.CompilerOptions,
@@ -64,8 +64,10 @@ export function getCompilerOptionsForEnv(
 }
 
 /**
- * Map package target to typecheck environments.
- * neutral/undefined → dual typecheck (node + browser).
+ * 패키지 target을 타입체크 환경으로 매핑한다.
+ * - server → ["node"], client → ["browser"]
+ * - node → ["node"], browser → ["browser"]
+ * - neutral/undefined → 이중 타입체크 (["node", "browser"]).
  */
 export function toTypecheckEnvs(target: string | undefined): TypecheckEnv[] {
   if (target === "node" || target === "server") return ["node"];
@@ -76,7 +78,7 @@ export function toTypecheckEnvs(target: string | undefined): TypecheckEnv[] {
 //#endregion
 
 /**
- * Parse tsconfig.json from the given directory.
+ * 지정된 디렉토리에서 tsconfig.json을 파싱한다.
  */
 export function parseTsconfig(dir: string): ts.ParsedCommandLine {
   const tsconfigPath = path.join(dir, "tsconfig.json");
@@ -98,7 +100,7 @@ export function parseTsconfig(dir: string): ts.ParsedCommandLine {
 }
 
 /**
- * Get source files (under src/) from a package, filtered by the parsed tsconfig.
+ * 패키지에서 소스 파일(src/ 하위)을 파싱된 tsconfig 기준으로 필터링하여 반환한다.
  */
 export function getPackageSourceFiles(
   pkgDir: string,
@@ -111,7 +113,7 @@ export function getPackageSourceFiles(
 }
 
 /**
- * Get all files (src + tests) from a package, filtered by the parsed tsconfig.
+ * 패키지의 모든 파일(src + tests)을 파싱된 tsconfig 기준으로 필터링하여 반환한다.
  */
 export function getPackageFiles(
   pkgDir: string,

package/src/utils/typecheck-non-package.ts

@@ -15,13 +15,12 @@ export interface NonPackageTypecheckResult {
 }
 
 /**
- * Typecheck non-package files (root-level configs + package root configs).
- * Extracted from dts.worker.ts non-package mode.
+ * 비패키지 파일(루트 레벨 설정 + 패키지 루트 설정)을 타입체크한다.
  *
- * Non-package files include:
- * - Root-level files (vitest.config.ts, etc.) — not under packages/
- * - Package root config files (packages/{pkg}/vitest.config.ts) — depth 2 under packages/
- * Excludes package source files (packages/{pkg}/src/...)
+ * 비패키지 파일 범위:
+ * - 루트 레벨 파일 (vitest.config.ts 등) — packages/ 외부
+ * - 패키지 루트 설정 파일 (packages/{pkg}/vitest.config.ts) — packages/ 하위 깊이 2
+ * 패키지 소스 파일(packages/{pkg}/src/...)은 제외한다.
  */
 export function typecheckNonPackageFiles(cwd: string): NonPackageTypecheckResult {
   logger.debug("비패키지 파일 타입체크 시작");
@@ -32,10 +31,10 @@ export function typecheckNonPackageFiles(cwd: string): NonPackageTypecheckResult
     const normalized = pathx.posixResolve(fileName);
     const normalizedPkgDir = pathx.posixResolve(packagesDir);
 
-    // Files outside packages/ directory
+    // packages/ 디렉토리 외부 파일
     if (!normalized.startsWith(normalizedPkgDir + "/")) return true;
 
-    // Files directly in package root (e.g., packages/{pkg}/file.ts — depth 2)
+    // 패키지 루트에 직접 위치한 파일 (예: packages/{pkg}/file.ts — 깊이 2)
     const relative = pathx.posix(path.relative(normalizedPkgDir, normalized));
     return relative.split("/").length === 2;
   };

package/src/utils/typecheck-serialization.ts

@@ -2,7 +2,7 @@ import ts from "typescript";
 import { fsx } from "@simplysm/core-node";
 
 /**
- * Serialized Diagnostic that can be passed to Worker
+ * Worker로 전달할 수 있는 직렬화된 Diagnostic
  */
 export interface SerializedDiagnostic {
   category: number;
@@ -16,11 +16,11 @@ export interface SerializedDiagnostic {
 }
 
 /**
- * Convert Diagnostic to serializable form
- * (remove circular references/functions for structured clone communication between Worker threads)
+ * Diagnostic을 직렬화 가능한 형태로 변환한다.
+ * (Worker 스레드 간 structured clone 통신을 위해 순환 참조/함수를 제거)
  */
 export function serializeDiagnostic(diagnostic: ts.Diagnostic): SerializedDiagnostic {
-  // If DiagnosticMessageChain, flatten entire chain to preserve all context info
+  // DiagnosticMessageChain인 경우 모든 컨텍스트 정보를 보존하기 위해 전체 체인을 평탄화
   const messageText = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
 
   return {
@@ -38,22 +38,20 @@ export function serializeDiagnostic(diagnostic: ts.Diagnostic): SerializedDiagno
 }
 
 /**
- * Determine TypeScript ScriptKind from filename
+ * 파일명에서 TypeScript ScriptKind를 결정한다.
  */
 function getScriptKind(fileName: string): ts.ScriptKind {
-  if (fileName.endsWith(".tsx")) return ts.ScriptKind.TSX;
-  if (fileName.endsWith(".jsx")) return ts.ScriptKind.JSX;
   if (fileName.endsWith(".js") || fileName.endsWith(".mjs") || fileName.endsWith(".cjs"))
     return ts.ScriptKind.JS;
   return ts.ScriptKind.TS;
 }
 
 /**
- * Restore SerializedDiagnostic to ts.Diagnostic
- * Reads actual file contents so source code context is displayed in formatDiagnosticsWithColorAndContext
- * @param serialized - Serialized diagnostic information
- * @param fileCache - File content cache (prevent duplicate reads of same file)
- * @returns Restored ts.Diagnostic object
+ * SerializedDiagnostic을 ts.Diagnostic으로 복원한다.
+ * formatDiagnosticsWithColorAndContext에서 소스 코드 컨텍스트가 표시되도록 실제 파일 내용을 읽는다.
+ * @param serialized - 직렬화된 진단 정보
+ * @param fileCache - 파일 내용 캐시 (같은 파일의 중복 읽기 방지)
+ * @returns 복원된 ts.Diagnostic 객체
  */
 export function deserializeDiagnostic(
   serialized: SerializedDiagnostic,
@@ -63,9 +61,9 @@ export function deserializeDiagnostic(
   if (serialized.file != null) {
     const fileName = serialized.file.fileName;
 
-    // Get cached file content (read and cache if not present)
-    // If file was deleted or inaccessible, treat as empty content
-    // (source code context won't be displayed but diagnostic message is shown normally)
+    // 캐시된 파일 내용 가져오기 (없으면 읽어서 캐시)
+    // 파일이 삭제되었거나 접근 불가능하면 빈 내용으로 처리
+    // (소스 코드 컨텍스트는 표시되지 않지만 진단 메시지는 정상 표시됨)
     if (!fileCache.has(fileName)) {
       fileCache.set(fileName, fsx.existsSync(fileName) ? fsx.readSync(fileName) : "");
     }