@simplysm/sd-cli 14.0.11 → 14.0.13

package/src/utils/copy-public.ts

@@ -6,17 +6,17 @@ import {
 } from "@simplysm/core-node";
 
 /**
- * Copy files from public/ and public-dev/ directories to dist/.
- * public-dev/ takes priority over public/ (overlay).
+ * public/ 및 public-dev/ 디렉토리의 파일을 dist/로 복사한다.
+ * public-dev/가 public/보다 우선한다 (오버레이).
  *
- * @param pkgDir Package root directory
- * @param includeDev Whether to include public-dev/ (true only in dev mode)
+ * @param pkgDir 패키지 루트 디렉토리
+ * @param includeDev public-dev/ 포함 여부 (dev 모드에서만 true)
  */
 export async function copyPublicFiles(pkgDir: string, includeDev: boolean): Promise<void> {
   const distDir = pathx.posix(path.join(pkgDir, "dist"));
   await fsx.mkdir(distDir);
 
-  // Copy public/
+  // public/ 복사
   const publicDir = pathx.posix(path.join(pkgDir, "public"));
   if (await fsx.exists(publicDir)) {
     const files = await fsx.glob("**/*", { cwd: publicDir, absolute: true });
@@ -30,7 +30,7 @@ export async function copyPublicFiles(pkgDir: string, includeDev: boolean): Prom
     );
   }
 
-  // Copy public-dev/ (overlay: overwrites public/)
+  // public-dev/ 복사 (오버레이: public/ 덮어쓰기)
   if (includeDev) {
     const publicDevDir = pathx.posix(path.join(pkgDir, "public-dev"));
     if (await fsx.exists(publicDevDir)) {
@@ -48,12 +48,12 @@ export async function copyPublicFiles(pkgDir: string, includeDev: boolean): Prom
 }
 
 /**
- * Watch public/ and public-dev/ directories and copy files to dist/ in real-time.
- * Automatically reflects changes/additions/deletions after initial copy.
+ * public/ 및 public-dev/ 디렉토리를 감시하고 변경사항을 실시간으로 dist/에 복사한다.
+ * 초기 복사 후 변경/추가/삭제를 자동으로 반영한다.
  *
- * @param pkgDir Package root directory
- * @param includeDev Whether to include public-dev/ (true only in dev mode)
- * @returns FsWatcher instance (must call close() on shutdown) or undefined if no watch targets
+ * @param pkgDir 패키지 루트 디렉토리
+ * @param includeDev public-dev/ 포함 여부 (dev 모드에서만 true)
+ * @returns FsWatcher 인스턴스 (종료 시 close() 호출 필요) 또는 감시 대상이 없으면 undefined
  */
 export async function watchPublicFiles(
   pkgDir: string,
@@ -63,10 +63,10 @@ export async function watchPublicFiles(
   const publicDir = pathx.posix(path.join(pkgDir, "public"));
   const publicDevDir = pathx.posix(path.join(pkgDir, "public-dev"));
 
-  // Initial copy
+  // 초기 복사
   await copyPublicFiles(pkgDir, includeDev);
 
-  // Collect watch target paths
+  // 감시 대상 경로 수집
   const watchPaths: string[] = [];
   if (await fsx.exists(publicDir)) {
     watchPaths.push(pathx.posix(path.join(publicDir, "**/*")));
@@ -83,7 +83,7 @@ export async function watchPublicFiles(
 
   watcher.onChange({ delay: 300 }, async (changes) => {
     for (const { event, path: filePath } of changes) {
-      // Determine which source directory the change came from
+      // 변경이 발생한 소스 디렉토리 결정
       let sourceDir: string;
       if (pathx.isChildPath(filePath, publicDevDir)) {
         sourceDir = publicDevDir;
@@ -95,14 +95,14 @@ export async function watchPublicFiles(
       const distPath = pathx.posix(path.join(distDir, relPath));
 
       if (event === "unlink") {
-        // If deleted from public, don't delete if same file exists in public-dev
+        // public에서 삭제된 경우, public-dev에 같은 파일이 있으면 삭제하지 않음
         if (sourceDir === publicDir && includeDev) {
           const devOverride = pathx.posix(path.join(publicDevDir, relPath));
           if (await fsx.exists(devOverride)) {
             continue;
           }
         }
-        // If deleted from public-dev, restore from public if it exists (fallback restore)
+        // public-dev에서 삭제된 경우, public에 파일이 있으면 복원 (폴백 복원)
         if (sourceDir === publicDevDir && includeDev) {
           const publicFallback = pathx.posix(path.join(publicDir, relPath));
           if (await fsx.exists(publicFallback)) {
@@ -113,7 +113,7 @@ export async function watchPublicFiles(
         }
         await fsx.rm(distPath);
       } else if (event === "add" || event === "change") {
-        // If changed in public, skip if same file exists in public-dev (overlay takes priority)
+        // public에서 변경된 경우, public-dev에 같은 파일이 있으면 스킵 (오버레이 우선)
         if (sourceDir === publicDir && includeDev) {
           const devOverride = pathx.posix(path.join(publicDevDir, relPath));
           if (await fsx.exists(devOverride)) {

package/src/utils/copy-src.ts

@@ -2,11 +2,11 @@ import path from "path";
 import { fsx, pathx, FsWatcher } from "@simplysm/core-node";
 
 /**
- * Copy files matching glob patterns from src/ to dist/
- * Relative paths are preserved: src/a/b.css → dist/a/b.css
+ * glob 패턴에 매칭되는 파일을 src/에서 dist/로 복사한다.
+ * 상대 경로가 유지된다: src/a/b.css → dist/a/b.css
  *
- * @param pkgDir Package root directory
- * @param patterns Array of glob patterns (relative to src/)
+ * @param pkgDir 패키지 루트 디렉토리
+ * @param patterns glob 패턴 배열 (src/ 기준 상대 경로)
  */
 export async function copySrcFiles(pkgDir: string, patterns: string[]): Promise<void> {
   const srcDir = pathx.posix(path.join(pkgDir, "src"));
@@ -26,21 +26,21 @@ export async function copySrcFiles(pkgDir: string, patterns: string[]): Promise<
 }
 
 /**
- * Watch and copy files matching glob patterns from src/ to dist/
- * Automatically reflects changes, additions, and deletions after initial copy.
+ * glob 패턴에 매칭되는 파일을 src/에서 dist/로 감시하며 복사한다.
+ * 초기 복사 후 변경, 추가, 삭제를 자동으로 반영한다.
  *
- * @param pkgDir Package root directory
- * @param patterns Array of glob patterns (relative to src/)
- * @returns FsWatcher instance (call close() on shutdown)
+ * @param pkgDir 패키지 루트 디렉토리
+ * @param patterns glob 패턴 배열 (src/ 기준 상대 경로)
+ * @returns FsWatcher 인스턴스 (종료 시 close() 호출)
  */
 export async function watchCopySrcFiles(pkgDir: string, patterns: string[]): Promise<FsWatcher> {
   const srcDir = pathx.posix(path.join(pkgDir, "src"));
   const distDir = pathx.posix(path.join(pkgDir, "dist"));
 
-  // Initial copy
+  // 초기 복사
   await copySrcFiles(pkgDir, patterns);
 
-  // Start watch
+  // 감시 시작
   const watchPaths = patterns.map((p) => pathx.posix(path.join(srcDir, p)));
   const watcher = await FsWatcher.watch(watchPaths);
 

package/src/utils/engine-stop.ts

@@ -1,8 +1,8 @@
 /**
- * Shared stop logic for build engines (BaseEngine, ViteEngine).
+ * 빌드 엔진(BaseEngine, ViteEngine)의 공유 중지 로직.
  *
- * Extracted to avoid duplicating the shutdown timeout + stopWatch race + terminate
- * pattern across engine implementations.
+ * 엔진 구현체 간 shutdown 타임아웃 + stopWatch 경쟁 + terminate
+ * 패턴의 중복을 방지하기 위해 추출하였다.
  */
 
 const SHUTDOWN_TIMEOUT = 3000;
@@ -13,14 +13,13 @@ interface StoppableWorker {
 }
 
 /**
- * Gracefully stop a build engine worker.
+ * 빌드 엔진 워커를 정상적으로 중지한다.
  *
- * In watch mode, attempts `stopWatch()` with a timeout guard so a hung worker
- * does not block shutdown. Then terminates the worker regardless.
+ * watch 모드에서는 타임아웃 가드와 함께 `stopWatch()`를 시도하여
+ * 멈춘 워커가 종료를 차단하지 않도록 한다. 이후 워커를 무조건 종료한다.
  *
- * @param worker - The worker proxy to stop (may be undefined if never started)
- * @param isWatchMode - Whether the engine is in watch mode
- * @returns A cleanup function that nullifies the caller's worker reference
+ * @param worker - 중지할 워커 프록시 (시작하지 않았으면 undefined)
+ * @param isWatchMode - watch 모드 여부
  */
 export async function stopEngineWorker(
   worker: StoppableWorker | undefined,
@@ -33,7 +32,7 @@ export async function stopEngineWorker(
         new Promise<void>((resolve) => setTimeout(resolve, SHUTDOWN_TIMEOUT)),
       ]);
     } catch {
-      // Continue even if stopWatch fails
+      // stopWatch 실패해도 계속 진행
     }
   }
 

package/src/utils/esbuild-config.ts

@@ -8,11 +8,11 @@ import { consola } from "consola";
 const logger = consola.withTag("sd:cli:esbuild-config");
 
 /**
- * Write only changed files from esbuild outputFiles to disk
+ * esbuild outputFiles에서 변경된 파일만 디스크에 쓴다.
  *
- * - .js files: Add .js extension to ESM relative import paths before comparing
- * - Other files (.js.map etc): Compare original content as-is
- * - Skip writing if content matches existing file to preserve timestamps
+ * - .js 파일: 비교 전 ESM 상대 import 경로에 .js 확장자를 추가한다
+ * - 기타 파일(.js.map 등): 원본 내용을 그대로 비교한다
+ * - 기존 파일과 내용이 동일하면 타임스탬프 보존을 위해 쓰기를 스킵한다
  */
 export async function writeChangedOutputFiles(outputFiles: esbuild.OutputFile[]): Promise<boolean> {
   logger.debug(`변경된 출력 파일 쓰기 시작 (${outputFiles.length}개)`);
@@ -33,7 +33,7 @@ export async function writeChangedOutputFiles(outputFiles: esbuild.OutputFile[])
         const existing = await fs.readFile(file.path, "utf-8");
         if (existing === finalText) return;
       } catch {
-        // File doesn't exist yet
+        // 파일이 아직 존재하지 않음
       }
 
       hasChanges = true;
@@ -46,23 +46,23 @@ export async function writeChangedOutputFiles(outputFiles: esbuild.OutputFile[])
 }
 
 /**
- * esbuild options for Server build
- * - bundle: true (single bundle with all dependencies)
+ * Server 빌드용 esbuild 옵션
+ * - bundle: true (모든 의존성을 포함한 단일 번들)
  */
 export interface ServerEsbuildOptions {
   pkgDir: string;
   entryPoints: string[];
   env?: Record<string, string>;
-  /** External modules to exclude from bundle */
+  /** 번들에서 제외할 외부 모듈 */
   external?: string[];
-  /** Dev mode: skip minification for faster builds */
+  /** dev 모드: 빠른 빌드를 위해 minification 스킵 */
   dev?: boolean;
 }
 
 /**
- * Generate a JS banner snippet that merges env vars into process.env at runtime.
- * Uses ??= so that runtime ENV (e.g. `DEV=false node server.js`) takes precedence
- * over build-time defaults.
+ * 런타임에 환경변수를 process.env에 병합하는 JS 배너 스니펫을 생성한다.
+ * ??=를 사용하여 런타임 ENV(예: `DEV=false node server.js`)가
+ * 빌드 타임 기본값보다 우선하도록 한다.
  */
 export function createEnvBanner(env?: Record<string, string>): string {
   if (env == null || Object.keys(env).length === 0) return "";
@@ -70,12 +70,12 @@ export function createEnvBanner(env?: Record<string, string>): string {
 }
 
 /**
- * Create esbuild config for Server build
+ * Server 빌드용 esbuild 설정을 생성한다.
  *
- * Used for server package builds
- * - bundle: true (single bundle with all dependencies)
- * - minify: true (minify for code protection)
- * - banner: createRequire shim for CJS package require() support + env injection
+ * server 패키지 빌드에 사용한다.
+ * - bundle: true (모든 의존성을 포함한 단일 번들)
+ * - minify: true (코드 보호를 위한 minify)
+ * - banner: CJS 패키지 require() 지원을 위한 createRequire shim + 환경변수 주입
  */
 export function createServerEsbuildOptions(options: ServerEsbuildOptions): esbuild.BuildOptions {
   const envBanner = createEnvBanner(options.env);
@@ -107,7 +107,7 @@ interface PkgJson {
 }
 
 /**
- * Recursively scan dependency tree and collect externals based on predicate
+ * 의존성 트리를 재귀적으로 스캔하고 predicate 기반으로 externals를 수집한다.
  */
 function scanDependencyTree(
   pkgName: string,
@@ -132,13 +132,13 @@ function scanDependencyTree(
   const depDir = path.dirname(pkgJsonPath);
   const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf-8")) as PkgJson;
 
-  // Collect packages marked as external by predicate
+  // predicate에 의해 external로 표시된 패키지 수집
   const toExternal = collector(pkgName, depDir, pkgJson);
   for (const name of toExternal) {
     external.add(name);
   }
 
-  // Recursively traverse sub-dependencies
+  // 하위 의존성 재귀 탐색
   const subDeps = Object.keys(pkgJson.dependencies ?? {});
   if (subDeps.length > 0) {
     logger.debug(
@@ -151,7 +151,7 @@ function scanDependencyTree(
 }
 
 /**
- * Collect both uninstalled optional peer deps and native modules in a single tree traversal
+ * 단일 트리 탐색으로 미설치 optional peer deps와 네이티브 모듈을 모두 수집한다.
  */
 export function collectAllDependencyExternals(pkgDir: string): {
   optionalPeerDeps: string[];
@@ -178,7 +178,7 @@ export function collectAllDependencyExternals(pkgDir: string): {
       (pkgName, depDir, depPkgJson) => {
         const found: string[] = [];
 
-        // Optional peer deps check
+        // Optional peer deps 확인
         if (depPkgJson.peerDependenciesMeta != null) {
           const peerDeps = depPkgJson.peerDependencies ?? {};
           const depReq = createRequire(path.join(depDir, "noop.js"));
@@ -193,7 +193,7 @@ export function collectAllDependencyExternals(pkgDir: string): {
           }
         }
 
-        // Native module check
+        // 네이티브 모듈 확인
         if (existsSync(path.join(depDir, "binding.gyp"))) {
           nativeModules.add(pkgName);
         }
@@ -215,10 +215,10 @@ export function collectAllDependencyExternals(pkgDir: string): {
 }
 
 /**
- * Collect uninstalled optional peer deps from dependency tree
+ * 의존성 트리에서 미설치 optional peer deps를 수집한다.
  *
- * For server builds (bundle: true), specify uninstalled optional peer dependencies
- * as esbuild externals to prevent build failures
+ * server 빌드(bundle: true)에서 미설치 optional peer dependencies를
+ * esbuild externals로 지정하여 빌드 실패를 방지한다.
  */
 export function collectUninstalledOptionalPeerDeps(pkgDir: string): string[] {
   return collectAllDependencyExternals(pkgDir).optionalPeerDeps;
@@ -229,10 +229,10 @@ export function collectUninstalledOptionalPeerDeps(pkgDir: string): string[] {
 //#region Native Module Externals
 
 /**
- * Collect native modules with binding.gyp from dependencies
+ * 의존성에서 binding.gyp가 있는 네이티브 모듈을 수집한다.
  *
- * Native modules built with node-gyp cannot be bundled by esbuild,
- * so they must be specified as externals.
+ * node-gyp로 빌드된 네이티브 모듈은 esbuild로 번들링할 수 없으므로
+ * externals로 지정해야 한다.
  */
 export function collectNativeModuleExternals(pkgDir: string): string[] {
   return collectAllDependencyExternals(pkgDir).nativeModules;

package/src/utils/lint-with-program.ts

@@ -7,7 +7,7 @@ import { consola } from "consola";
 const logger = consola.withTag("sd:cli:lint-with-program");
 
 /**
- * Lint result returned by LintWithProgramRunner.lint()
+ * LintWithProgramRunner.lint()가 반환하는 lint 결과
  */
 export interface LintWithProgramResult {
   success: boolean;
@@ -17,7 +17,7 @@ export interface LintWithProgramResult {
 }
 
 /**
- * Options for LintWithProgramRunner constructor
+ * LintWithProgramRunner 생성자 옵션
  */
 export interface LintWithProgramRunnerOptions {
   cwd: string;
@@ -25,22 +25,22 @@ export interface LintWithProgramRunnerOptions {
 }
 
 /**
- * Options for LintWithProgramRunner.lint()
+ * LintWithProgramRunner.lint() 옵션
  */
 export interface LintRunOptions {
   program: ts.Program;
-  /** When provided, only files in this set are linted (intersection with extracted files).
-   *  Used in watch rebuild for incremental lint based on affected files. */
+  /** 제공 시 이 집합의 파일만 lint한다 (추출된 파일과의 교집합).
+   *  watch 재빌드에서 affected 파일 기반 증분 lint에 사용한다. */
   affectedFiles?: ReadonlySet<string>;
 }
 
 /**
- * Runs ESLint using an existing ts.Program (avoids duplicate Program creation).
+ * 기존 ts.Program을 사용하여 ESLint를 실행한다 (중복 Program 생성을 방지).
  *
- * - Extracts source files from program.getSourceFiles() filtered to pkgDir
- * - Excludes .d.ts files and node_modules paths
- * - Injects ts.Program via parserOptions.programs (typescript-eslint)
- * - Reuses ESLint instance across calls (watch mode optimization)
+ * - program.getSourceFiles()에서 pkgDir로 필터링하여 소스 파일을 추출한다
+ * - .d.ts 파일과 node_modules 경로를 제외한다
+ * - parserOptions.programs를 통해 ts.Program을 주입한다 (typescript-eslint)
+ * - 호출 간 ESLint 인스턴스를 재사용한다 (watch 모드 최적화)
  */
 export class LintWithProgramRunner {
   private readonly _cwd: string;
@@ -55,8 +55,8 @@ export class LintWithProgramRunner {
   }
 
   /**
-   * Extract lint target files from ts.Program.
-   * Includes all workspace source files (cwd scope), excludes .d.ts, node_modules, and Angular shims.
+   * ts.Program에서 lint 대상 파일을 추출한다.
+   * 모든 워크스페이스 소스 파일(cwd 범위)을 포함하고 .d.ts, node_modules, Angular shim을 제외한다.
    */
   private _extractFiles(program: ts.Program): string[] {
     logger.debug(`[${this._pkgName}] 린트 대상 파일 추출 시작`);
@@ -66,22 +66,22 @@ export class LintWithProgramRunner {
     for (const sf of program.getSourceFiles()) {
       const fileName = pathx.posix(sf.fileName);
 
-      // Must be within workspace root
+      // 워크스페이스 루트 내에 있어야 함
       if (!fileName.startsWith(normalizedCwd + "/")) {
         continue;
       }
 
-      // Exclude declaration files
+      // 선언 파일 제외
       if (sf.isDeclarationFile) {
         continue;
       }
 
-      // Exclude node_modules
+      // node_modules 제외
       if (fileName.includes("/node_modules/")) {
         continue;
       }
 
-      // Exclude Angular type-check shim files (virtual, not on disk)
+      // Angular 타입체크 shim 파일 제외 (가상 파일, 디스크에 없음)
       if (fileName.endsWith(".ngtypecheck.ts")) {
         continue;
       }
@@ -94,17 +94,17 @@ export class LintWithProgramRunner {
   }
 
   /**
-   * Run ESLint on files from the given ts.Program.
-   * When affectedFiles is provided, only the intersection is linted (watch rebuild).
-   * Creates ESLint instance on first call, reuses on subsequent calls.
+   * 주어진 ts.Program의 파일에 대해 ESLint를 실행한다.
+   * affectedFiles가 제공되면 교집합만 lint한다 (watch 재빌드).
+   * 첫 호출 시 ESLint 인스턴스를 생성하고, 이후 호출에서 재사용한다.
    */
   async lint(options: LintRunOptions): Promise<LintWithProgramResult> {
     const { program, affectedFiles } = options;
 
-    // Extract target files (workspace scope)
+    // 대상 파일 추출 (워크스페이스 범위)
     let files = this._extractFiles(program);
 
-    // When affectedFiles is provided, intersect with extracted files
+    // affectedFiles가 제공되면 추출된 파일과 교집합
     if (affectedFiles != null) {
       files = files.filter((f) => affectedFiles.has(pathx.posix(f)));
     }
@@ -118,23 +118,23 @@ export class LintWithProgramRunner {
       };
     }
 
-    // Update programs reference (mutable array — ESLint reads it on lintFiles)
+    // programs 참조 업데이트 (가변 배열 — ESLint가 lintFiles 시 읽음)
     this._programsRef.length = 0;
     this._programsRef.push(program);
 
-    // Cache policy: affected files-based incremental lint is more accurate than ESLint's
-    // file-content-based cache (which misses dependency changes).
-    // When affectedFiles is provided (watch rebuild), disable cache.
-    // When not provided (one-time build), enable cache for performance.
+    // 캐시 정책: affected 파일 기반 증분 lint가 ESLint의
+    // 파일 내용 기반 캐시(의존성 변경을 놓침)보다 정확하다.
+    // affectedFiles가 제공되면 (watch 재빌드) 캐시를 비활성화한다.
+    // 제공되지 않으면 (일회성 빌드) 성능을 위해 캐시를 활성화한다.
     const useCache = affectedFiles == null;
 
-    // Create new ESLint instance when cache policy changes or on first call
+    // 캐시 정책이 변경되거나 첫 호출 시 새 ESLint 인스턴스 생성
     if (this._eslint == null || this._lastUseCache !== useCache) {
       logger.debug(`[${this._pkgName}] ESLint 인스턴스 생성 (cache: ${String(useCache)})`);
-      // ESLint Flat Config serializes languageOptions via languageOptionsToJSON(),
-      // which recurses into parserOptions and throws on ts.Program methods.
-      // Adding toJSON() to parserOptions returns a serializable representation
-      // while keeping the actual programs array accessible to typescript-eslint.
+      // ESLint Flat Config는 languageOptionsToJSON()을 통해 languageOptions를 직렬화하는데,
+      // parserOptions를 재귀 탐색하면서 ts.Program 메서드에서 예외가 발생한다.
+      // parserOptions에 toJSON()을 추가하여 직렬화 가능한 표현을 반환하면서
+      // typescript-eslint가 실제 programs 배열에 접근할 수 있도록 한다.
       const parserOptions = {
         programs: this._programsRef,
         project: null,
@@ -157,11 +157,11 @@ export class LintWithProgramRunner {
       this._lastUseCache = useCache;
     }
 
-    // Run lint
+    // lint 실행
     logger.debug(`[${this._pkgName}] 린트 시작 (${files.length}개 파일, affected: ${affectedFiles != null})`);
     const results = await this._eslint.lintFiles(files);
 
-    // Aggregate results
+    // 결과 집계
     let errorCount = 0;
     let warningCount = 0;
     for (const r of results) {
@@ -169,7 +169,7 @@ export class LintWithProgramRunner {
       warningCount += r.warningCount;
     }
 
-    // Format output
+    // 출력 포맷팅
     const formatter = await this._eslint.loadFormatter("stylish");
     const formattedOutput = await formatter.format(results);
 

package/src/utils/ngtsc-build-core.ts

@@ -29,9 +29,9 @@ export interface NgtscBuildInfo {
   cwd: string;
   pkgDir: string;
   output: BuildOutput;
-  /** Typecheck environment. When set, adjusts compilerOptions via getCompilerOptionsForEnv(). */
+  /** 타입체크 환경. 설정 시 getCompilerOptionsForEnv()로 compilerOptions를 조정한다. */
   env?: TypecheckEnv;
-  /** replaceDeps configuration from sd.config.ts */
+  /** sd.config.ts의 replaceDeps 설정 */
   replaceDeps?: Record<string, string>;
 }
 
@@ -40,7 +40,7 @@ export interface NgtscBuildResult {
   lint?: LintWithProgramResult;
 }
 
-/** runNgtscBuild 내부 반환 타입. program은 워커 내에서 lint 용도로만 사용된다. */
+/** runNgtscBuild 내부 반환 타입. program은 워커 내에서 lint 용도로만 사용한다. */
 export interface NgtscBuildInternalResult extends NgtscBuildResult {
   program?: ts.Program;
 }
@@ -83,7 +83,7 @@ export function buildCompilerOptions(
     options.emitDeclarationOnly = true;
     options.declarationDir = path.join(pkgDir, "dist");
   } else {
-    // both false — typecheck only
+    // 둘 다 false — 타입체크만 수행
     options.noEmit = true;
     options.declaration = false;
     options.declarationMap = false;
@@ -199,12 +199,12 @@ export function writeEmitResults(
     if (rewrite == null) continue;
     let [newPath, newContent] = rewrite;
 
-    // Process side-effect SCSS imports in .js files
+    // .js 파일 내 side-effect SCSS import 처리
     if (scss != null && newPath.endsWith(".js")) {
       const { text, scssImports } = rewriteScssImports(newContent);
       newContent = text;
 
-      // Clear stale registry entries for this source file before registering new ones
+      // 새 항목 등록 전에 이 소스 파일의 기존 레지스트리 항목 제거
       if (scss.registry != null && sourceFileName != null) {
         for (const [key, entry] of scss.registry) {
           if (entry.sourceFileName === sourceFileName) {
@@ -222,7 +222,7 @@ export function writeEmitResults(
           const cssFileName = scssImport.replace(/\.scss$/, ".css");
           const cssAbsPath = path.resolve(outputDir, cssFileName);
 
-          // Register in registry if provided (keyed by scssAbsPath for uniqueness)
+          // 레지스트리가 제공된 경우 등록 (scssAbsPath를 키로 사용하여 중복 방지)
           if (scss.registry != null) {
             scss.registry.set(scssAbsPath, { scssAbsPath, cssAbsPath, sourceFileName });
           }
@@ -248,9 +248,9 @@ export function writeEmitResults(
 //#region Side-effect SCSS
 
 /**
- * Compile all side-effect SCSS entries in the registry to CSS.
- * Follows the same pattern as compileGlobalScss — always recompiles all entries.
- * On error, adds to scssErrors and preserves existing CSS file.
+ * 레지스트리의 모든 side-effect SCSS 항목을 CSS로 컴파일한다.
+ * compileGlobalScss와 동일한 패턴 — 항상 모든 항목을 재컴파일한다.
+ * 에러 발생 시 scssErrors에 추가하고 기존 CSS 파일을 보존한다.
  */
 export function compileSideEffectScss(
   registry: ReadonlyMap<string, SideEffectScssEntry>,
@@ -300,8 +300,8 @@ export function compileGlobalScss(
 //#endregion
 
 /**
- * Run a full Angular library build using AngularCompiler.
- * (parse, initialize, diagnostics, emit, global SCSS)
+ * AngularCompiler를 사용한 전체 Angular 라이브러리 빌드를 수행한다.
+ * (파싱, 초기화, 진단, emit, global SCSS)
  */
 export async function runNgtscBuild(info: NgtscBuildInfo): Promise<NgtscBuildInternalResult> {
   try {
@@ -328,7 +328,7 @@ export async function runNgtscBuild(info: NgtscBuildInfo): Promise<NgtscBuildInt
     const scssDependencies = new Map<string, Set<string>>();
     const loadPaths = buildScssLoadPaths(info);
 
-    // Create AngularCompiler
+    // AngularCompiler 생성
     logger.debug(`[${info.name}] AngularCompiler 생성 중...`);
     const compiler = new AngularCompiler({
       rootNames: sourceFiles,
@@ -337,12 +337,12 @@ export async function runNgtscBuild(info: NgtscBuildInfo): Promise<NgtscBuildInt
       transformStylesheet: createLibraryTransformStylesheet(loadPaths, scssErrors, scssDependencies),
     });
 
-    // Initialize (creates program, AOT analysis, finds affected files)
+    // 초기화 (프로그램 생성, AOT 분석, affected 파일 탐색)
     logger.debug(`[${info.name}] AngularCompiler 초기화 중...`);
     await compiler.initialize();
     logger.debug(`[${info.name}] AngularCompiler 초기화 완료`);
 
-    // Collect diagnostics — workspace scope (no package-level filtering)
+    // 진단 수집 — workspace 스코프 (패키지 단위 필터링 없음)
     const allDiagnostics = [...compiler.collectDiagnostics()].filter(
       (d) => isWorkspaceDiagnostic(d, info.cwd),
     );
@@ -357,7 +357,7 @@ export async function runNgtscBuild(info: NgtscBuildInfo): Promise<NgtscBuildInt
       .filter((d) => d.category === ts.DiagnosticCategory.Error)
       .map(formatDiagnosticError);
 
-    // Emit via AngularCompiler + output-path-rewriting
+    // AngularCompiler를 통한 emit + output-path-rewriting
     const emitResults = compiler.emitAffectedFiles({
       sourceFilter: (fileName: string) =>
         pathx.posix(fileName).startsWith(normalizedSrcDir + "/"),
@@ -368,7 +368,7 @@ export async function runNgtscBuild(info: NgtscBuildInfo): Promise<NgtscBuildInt
       scssDependencies,
     });
 
-    // Global SCSS compilation
+    // Global SCSS 컴파일
     const globalScssErrors = compileGlobalScss(info.pkgDir, loadPaths);
 
     const allErrors = [...errors, ...scssErrors, ...globalScssErrors];