@simplysm/sd-claude 14.0.88 → 14.0.89

package/claude/references/sd-simplysm14/apis/orm-node/db-conn.md

@@ -1,14 +1,14 @@
 # @simplysm/orm-node — 저수준 DB 연결
 
-`createOrm` 추상화 없이 직접 SQL/파라미터 쿼리/bulk insert/수동 트랜잭션을 다루거나, `DbContext` 의 executor 를 직접 구성할 때 사용하는 계층. 연결 인스턴스 생성·연결 인터페이스·접속설정·executor·dialect 헬퍼·상수로 구성.
+`createOrm` 추상화를 거치지 않고 raw SQL·파라미터 쿼리·bulk insert·수동 트랜잭션을 직접 다루거나, dialect별 접속 설정 타입을 작성하거나, `DbContext` 의 executor 를 직접 구성할 때 같이 읽히는 묶음. 연결 인스턴스 생성·연결 인터페이스·접속 설정·executor·dialect 헬퍼·상수로 구성.
 
 ## createDbConn
 
 ```typescript
-createDbConn(config: DbConnConfig): Promise<DbConn>
+function createDbConn(config: DbConnConfig): Promise<DbConn>
 ```
 
-`config.dialect` 에 맞는 드라이버를 **지연 import** 해 연결 인스턴스를 만든다(mysql → `mysql2/promise`, postgresql → `pg` + `pg-copy-streams`, mssql/mssql-azure → `tedious`). 한 번 로드한 드라이버는 모듈 캐시에 보관. 반환된 객체는 아직 **미연결** 상태이므로 `connect()` 를 별도 호출해야 함.
+`config.dialect` 에 맞는 드라이버를 **지연 import** 해 연결 인스턴스를 만든다(mysql → `mysql2/promise`, postgresql → `pg` + `pg-copy-streams`, mssql/mssql-azure → `tedious`). 한 번 로드한 드라이버는 모듈 캐시에 보관해 재사용. 반환 객체는 아직 **미연결** 상태이므로 `connect()` 를 별도 호출해야 함.
 
 ```typescript
 const conn = await createDbConn({ dialect: "postgresql", host: "localhost", username: "u", password: "p", database: "db" });
@@ -17,22 +17,22 @@ await conn.connect();
 
 ## DbConn
 
-저수준 연결 인터페이스. `EventEmitter<{ close: void }>` 를 상속하며 연결 종료 시 `close` 이벤트를 발생시킨다. 구현체 `MysqlDbConn`/`MssqlDbConn`/`PostgresqlDbConn` 는 직접 export 되지 않고 `createDbConn` 으로만 획득.
+저수준 연결 인터페이스. `EventEmitter<{ close: void }>` 를 상속하며 연결 종료 시 `close` 이벤트를 발생시킨다. 구현체 `MssqlDbConn`/`MysqlDbConn`/`PostgresqlDbConn` 는 직접 export 되지 않고 `createDbConn` 으로만 획득(타입 import 만 가능).
 
-- `config: DbConnConfig` — 이 연결의 접속설정(읽기전용).
-- `isConnected: boolean` — 현재 연결 여부. `connect` 성공 시 `true`, `close`/종료 이벤트 시 `false`.
-- `isInTransaction: boolean` — 트랜잭션 진행 여부. `beginTransaction` 후 `true`, 커밋/롤백 후 `false`.
+- `config: DbConnConfig` — 이 연결의 접속 설정(읽기 전용).
+- `isConnected: boolean` — 현재 연결 여부. `connect` 성공 시 `true`, `close`/종료(`end`) 이벤트 시 `false`. 상태 확인·재연결 판단에 사용.
+- `isInTransaction: boolean` — 트랜잭션 진행 여부. `beginTransaction` 후 `true`, 커밋·롤백 후 `false`.
 - `connect(): Promise<void>` — 연결 수립. 이미 연결돼 있으면 `DB_CONN_ERRORS.ALREADY_CONNECTED` throw.
-- `close(): Promise<void>` — 연결 종료. 미연결 상태면 아무 동작 없이 반환.
-- `beginTransaction(isolationLevel?: IsolationLevel): Promise<void>` — 트랜잭션 시작. `isolationLevel` 미지정 시 `config.defaultIsolationLevel`, 그것도 없으면 `READ_UNCOMMITTED`.
+- `close(): Promise<void>` — 연결 종료. 미연결 상태면 아무 동작 없이 반환(throw 안 함).
+- `beginTransaction(isolationLevel?: IsolationLevel): Promise<void>` — 트랜잭션 시작. `isolationLevel` 미지정 시 `config.defaultIsolationLevel`, 그것도 없으면 `READ_UNCOMMITTED` 로 시작. 테스트로 확인된 허용 값: `"READ_UNCOMMITTED"|"READ_COMMITTED"|"REPEATABLE_READ"|"SERIALIZABLE"`.
 - `commitTransaction(): Promise<void>` — 커밋.
 - `rollbackTransaction(): Promise<void>` — 롤백.
-- `execute(queries: string[]): Promise<Record<string, unknown>[][]>` — 원시 SQL 문자열 배열을 순차 실행. 빈 문자열은 건너뛰며, 각 쿼리의 결과셋을 평탄화해 묶은 배열 반환.
-- `executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>` — 파라미터 바인딩 쿼리 실행. SQL 인젝션 회피·값 재바인딩 시. 반환은 결과셋 배열(MySQL 멀티스테이트먼트는 statement별로 분리, INSERT/UPDATE/DELETE 자리는 빈 배열).
-- `bulkInsert(tableName: string, columnMetas: Record<string, ColumnMeta>, records: Record<string, unknown>[]): Promise<void>` — 네이티브 bulk API 로 대량 삽입. `tableName` 은 `database.table` 또는 `database.schema.table`. `columnMetas` 는 컬럼명 → `ColumnMeta`(타입·nullable) 매핑이며 키 순서가 컬럼 순서를 결정. `records` 가 빈 배열이면 아무 동작 없이 반환. dialect별 경로: MSSQL tedious BulkLoad, MySQL `LOAD DATA LOCAL INFILE`(임시 CSV 파일 생성·삭제, UUID/binary 는 `UNHEX`), PostgreSQL `COPY FROM STDIN`(CSV 스트림).
+- `execute(queries: string[]): Promise<Record<string, unknown>[][]>` — 원시 SQL 문자열 배열을 순차 실행. 빈/공백 문자열은 건너뜀. 각 쿼리의 결과셋들을 평탄화해 하나의 배열로 묶어 반환. DDL·다건 SQL 일괄 실행에 사용.
+- `executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>` — 파라미터 바인딩 쿼리 실행. SQL 인젝션 회피·값 재바인딩 시. 반환은 결과셋 배열(MySQL 멀티스테이트먼트는 statement별로 분리되며 INSERT/UPDATE/DELETE 자리는 빈 배열, PostgreSQL 은 단일 결과셋). `params` 미지정 시 MSSQL 은 배치(`execSqlBatch`) 경로로 실행.
+- `bulkInsert(tableName: string, columnMetas: Record<string, ColumnMeta>, records: Record<string, unknown>[]): Promise<void>` — 네이티브 bulk API 로 대량 삽입. `tableName` 은 `database.table` 또는 `database.schema.table`(dialect별 인용 부호 포함된 완전 수식명). `columnMetas` 는 컬럼명 → `ColumnMeta`(`dataType`·`nullable`) 매핑이며 **키 순서가 컬럼 순서를 결정**, `records` 의 각 객체는 이 키들로 값 추출. `records` 가 빈 배열이면 아무 동작 없이 반환. dialect별 경로: MSSQL tedious `BulkLoad`, MySQL `LOAD DATA LOCAL INFILE`(임시 CSV 파일 생성·삭제, UUID/binary 는 `UNHEX`), PostgreSQL `COPY FROM STDIN`(CSV 스트림). `DateTime`/`DateOnly`/`Time`/`Uuid`/`Uint8Array` 값은 dialect별로 적절히 변환됨.
 
 ```typescript
-await conn.beginTransaction();
+await conn.beginTransaction("READ_COMMITTED");
 const [rows] = await conn.executeParametrized('SELECT * FROM "User" WHERE id = $1', [1]);
 await conn.commitTransaction();
 ```
@@ -43,13 +43,13 @@ await conn.commitTransaction();
 
 공통 필드:
 
-- `dialect` — `"mysql"` | `"mssql"` | `"mssql-azure"` | `"postgresql"`. DBMS 선택. `"mssql-azure"` 는 Azure SQL 용으로 드라이버는 mssql 과 동일하되 연결 시 `encrypt` 활성화. 쿼리 빌더용으로는 `getDialectFromConfig` 가 `"mssql"` 로 정규화.
+- `dialect` — `"mysql"` | `"mssql"` | `"mssql-azure"` | `"postgresql"`. DBMS 선택. `"mssql-azure"` 는 Azure SQL 용으로 드라이버는 mssql 과 동일하되 연결 시 `encrypt` 활성화. 쿼리 빌더용 dialect 로는 `getDialectFromConfig` 가 `"mssql"` 로 정규화.
 - `host: string` — 접속 호스트.
-- `port?: number` — 포트. 미지정 시 드라이버 기본값(PostgreSQL 은 5432 로 보정).
+- `port?: number` — 포트. 미지정 시 드라이버 기본값(PostgreSQL 은 미지정 시 5432 로 보정).
 - `username: string` — 인증 사용자.
 - `password: string` — 인증 비밀번호.
-- `database?: string` — 기본 DB 이름.
-- `defaultIsolationLevel?: IsolationLevel` — `beginTransaction` 의 `isolationLevel` 미지정 시 적용할 기본 격리수준.
+- `database?: string` — 접속 기본 DB 이름.
+- `defaultIsolationLevel?: IsolationLevel` — `beginTransaction` 의 `isolationLevel` 미지정 시 적용할 기본 격리 수준.
 
 dialect별 추가 필드:
 
@@ -60,10 +60,10 @@ dialect별 추가 필드:
 ## getDialectFromConfig
 
 ```typescript
-getDialectFromConfig(config: DbConnConfig): Dialect
+function getDialectFromConfig(config: DbConnConfig): Dialect
 ```
 
-`config.dialect` 를 `@simplysm/orm-common` 의 `Dialect` 로 변환. `"mssql-azure"` → `"mssql"` 로 정규화하고 나머지는 그대로 반환. 쿼리 빌더의 dialect 결정에 사용.
+`config.dialect` 를 `@simplysm/orm-common` 의 `Dialect` 로 변환. `"mssql-azure"` → `"mssql"` 로 정규화하고 나머지는 그대로 반환. 쿼리 빌더의 dialect 결정에 사용. Azure 여부와 무관하게 같은 SQL 방언을 써야 할 때.
 
 ## NodeDbContextExecutor
 
@@ -71,24 +71,24 @@ getDialectFromConfig(config: DbConnConfig): Dialect
 new NodeDbContextExecutor(config: DbConnConfig)
 ```
 
-`@simplysm/orm-common` 의 `DbContextExecutor` 를 Node 환경에서 구현한 클래스. `createOrm` 이 내부에서 자동 주입하므로 보통 직접 쓸 일은 없고, `DbContext` 를 `createOrm` 없이 수동 인스턴스화할 때만 사용. 생성자에는 `DbConnConfig` 만 받고, 실제 연결은 `connect()` 시점에 `createDbConn` 으로 지연 생성한다.
+`@simplysm/orm-common` 의 `DbContextExecutor` 를 Node 환경에서 구현한 클래스. `createOrm` 이 내부에서 자동 주입하므로 보통 직접 쓸 일은 없고, `DbContext` 를 `createOrm` 없이 수동 인스턴스화할 때만 사용. 생성자는 `DbConnConfig` 만 받고, 실제 연결은 `connect()` 시점에 `createDbConn` 으로 지연 생성한다.
 
 - `connect(): Promise<void>` — `createDbConn(config)` 로 연결 생성 후 수립.
 - `close(): Promise<void>` — 연결 종료 후 내부 참조 해제.
-- `beginTransaction(isolationLevel?: IsolationLevel)` / `commitTransaction()` / `rollbackTransaction()` — 트랜잭션 위임.
+- `beginTransaction(isolationLevel?: IsolationLevel)` / `commitTransaction()` / `rollbackTransaction()` — 내부 `DbConn` 에 트랜잭션 위임.
 - `executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>` — 파라미터 쿼리 위임.
 - `bulkInsert(tableName: string, columnMetas: Record<string, ColumnMeta>, records: DataRecord[]): Promise<void>` — bulk insert 위임.
-- `executeDefs<T>(defs: QueryDef[], resultMetas?: (ResultMeta | undefined)[]): Promise<T[][]>` — `QueryDef` 배열을 dialect 쿼리 빌더로 SQL 변환해 실행. `resultMetas` 가 전부 `null`/미지정이면(결과 불필요) 모든 def 를 하나의 SQL 로 합쳐 단일 요청으로 보내고 def 수만큼 빈 배열 반환(쓰기 전용 최적화). 그 외엔 def 마다 개별 실행 후, 해당 위치에 `resultMeta` 가 있으면 `parseQueryResult` 로 타입 변환해 반환.
+- `executeDefs<T>(defs: QueryDef[], resultMetas?: (ResultMeta | undefined)[]): Promise<T[][]>` — `QueryDef` 배열을 dialect 쿼리 빌더로 SQL 변환해 실행. `resultMetas` 가 전부 `null`/미지정이면(결과 불필요) 모든 def 를 하나의 SQL 로 합쳐 단일 요청으로 보내고 def 수만큼 빈 배열 반환(쓰기 전용 최적화). 그 외엔 def 마다 개별 실행 후, 해당 위치에 `resultMeta` 가 있으면 `parseQueryResult` 로 타입 변환해 반환, 없으면 raw 결과셋 그대로 반환.
 - 모든 실행 메서드는 미연결 상태에서 호출 시 `SdError(DB_CONN_ERRORS.NOT_CONNECTED)` throw.
 
 ## 상수
 
-- `DB_CONN_CONNECT_TIMEOUT` — 연결 수립 타임아웃. `10 * 1000`(10초).
-- `DB_CONN_DEFAULT_TIMEOUT` — 쿼리 기본 타임아웃. `10 * 60 * 1000`(10분). 마지막 활동 후 이 값의 2배가 지나면 연결을 자동 종료(idle 타임아웃).
-- `DB_CONN_ERRORS` — 오류 메시지 상수 객체. `NOT_CONNECTED`(미연결 상태 실행 시), `ALREADY_CONNECTED`(이미 연결된 상태에서 재연결 시). `expect(...).rejects.toThrow(DB_CONN_ERRORS.NOT_CONNECTED)` 처럼 throw 비교·메시지 매칭에 사용.
+- `DB_CONN_CONNECT_TIMEOUT` — 연결 수립 타임아웃. `10 * 1000`(10초). 연결 드라이버의 connect 타임아웃으로 전달.
+- `DB_CONN_DEFAULT_TIMEOUT` — 쿼리 기본 타임아웃. `10 * 60 * 1000`(10분). 마지막 활동 후 이 값의 2배가 지나면 연결을 자동 종료(idle 타임아웃)하는 데도 사용.
+- `DB_CONN_ERRORS` — 오류 메시지 상수 객체(`as const`). `NOT_CONNECTED`(미연결 상태에서 실행 시), `ALREADY_CONNECTED`(이미 연결된 상태에서 재연결 시). `expect(...).rejects.toThrow(DB_CONN_ERRORS.NOT_CONNECTED)` 처럼 throw 비교·메시지 매칭에 사용.
 
 ## 주의사항
 
 - `createDbConn` 반환 객체는 미연결 상태 — 반드시 `connect()` 호출 후 사용.
-- bulk insert 는 dialect별 네이티브 경로가 달라(MySQL 은 임시파일 + `LOCAL INFILE`, PostgreSQL 은 `COPY`) 서버 측 권한·설정에 의존할 수 있음.
-- 대부분의 작업은 `createOrm`(README)으로 충분. 이 계층은 원시 SQL·executor 커스터마이징이 필요한 경우에만.
+- bulk insert 는 dialect별 네이티브 경로가 달라(MySQL 임시파일 + `LOCAL INFILE`, PostgreSQL `COPY`, MSSQL `BulkLoad`) 서버 측 권한·설정에 의존할 수 있음.
+- 대부분의 작업은 `createOrm`(README)으로 충분. 이 계층은 raw SQL·executor 커스터마이징이 필요한 경우에만.

package/claude/references/sd-simplysm14/apis/sd-cli/README.md

@@ -1,29 +1,26 @@
 # @simplysm/sd-cli
 
-simplysm 모노레포의 빌드/배포 오케스트레이터 CLI. entry(`src/index.ts`)가 라이브러리로 재노출하는 것은 `sd.config.ts` 작성용 설정 타입 묶음, Vitest용 Angular AOT Vite 플러그인, 프로그래밍 방식 TS/Angular AOT 컴파일러 클래스 3종. (CLI 서브커맨드 구현 자체는 entry export 대상 아님.)
+simplysm 빌드/배포 오케스트레이터 CLI. entry 에서 공개되는 것은 CLI 실행 코드가 아니라 ① `sd.config.ts` 작성용 설정 타입, ② 내부 TypeScript/Angular 컴파일러(`SdTsCompiler`), ③ Vitest 전용 Angular Vite 플러그인(`sdAngularPlugin`) 세 가지뿐이다.
 
 ## 사용 트리거 인덱스
 
-- **sd.config.ts 설정 타입** (`SdConfig`, `SdConfigFn`, `SdConfigParams`, `SdPackageConfig` 계열, `SdPublishConfig` 계열, Capacitor/Electron/PWA 설정 등) — 프로젝트 루트 `sd.config.ts` 를 작성·수정해 패키지 빌드 타겟·배포·앱 패키징을 설정할 때. 자세히: [sd-config-types.md](./sd-config-types.md)
-- **SdTsCompiler** (`SdTsCompiler`, `ISdTsCompilerOptions`, `ISdTsCompilerResult`) — 패키지의 `.ts` 를 TS/Angular AOT 로 증분 컴파일하고 진단·emit·lint·SCSS 결과를 한 번에 얻을 때 (빌드 엔진·플러그인 내부에서 사용). 자세히: [SdTsCompiler.md](./SdTsCompiler.md)
-- **sdAngularPlugin** — Vitest 에서 Angular 패키지를 AOT 컴파일해 TestBed 로 돌리기 위한 Vite 플러그인을 `vitest.config.ts` 에 끼울 때. 아래 인라인 섹션 참조.
+- **sd.config.ts 설정 타입** — 프로젝트 루트 `sd.config.ts` 를 작성·수정하며 패키지 빌드 타겟·배포·Capacitor/Electron/PWA·서버 옵션을 지정할 때. 자세히: [sd-config-types.md](./sd-config-types.md)
+- **SdTsCompiler / ISdTsCompilerOptions / ISdTsCompilerResult** — sd-cli 외부에서 패키지 단위 TS(또는 Angular AOT) 증분 컴파일을 직접 구동하거나 그 결과(emit·진단·lint·SCSS)를 다룰 때. 자세히: [SdTsCompiler.md](./SdTsCompiler.md)
+- **sdAngularPlugin / SdAngularPluginOptions** — Vitest 의 Angular project 에서 `.ts` 를 AOT 컴파일해 주입하는 Vite 플러그인을 설정할 때. (인라인, 아래 참조)
 
 ## sdAngularPlugin
 
-Vitest 전용 Vite 플러그인. `SdTsCompiler` 로 대상 패키지의 `.ts` 를 AOT 컴파일하고, `transform` 훅에서 컴파일된 JS 를 반환한다.
-
-```typescript
-function sdAngularPlugin(options: SdAngularPluginOptions): Plugin
+```ts
+function sdAngularPlugin(options: SdAngularPluginOptions): Plugin   // vite Plugin 반환
+interface SdAngularPluginOptions { pkg: string }
 ```
 
-`SdAngularPluginOptions`:
-
-- pkg: string — `sd.config.ts` 의 `packages` 키(패키지 디렉토리명, `@simplysm/` 접두사 제외). `config()` 훅에서 `packages/<pkg>` 를 컴파일 루트로 해석한다. 어느 Angular 패키지를 테스트 빌드할지 지정.
+Angular AOT 컴파일을 수행하는 Vite 플러그인. **Vitest 전용**(`vitest.config.ts` 의 `angular` project plugins 에 등록). 내부적으로 `SdTsCompiler` 로 대상 패키지의 `.ts`(tests 포함, `includeTests: true`)를 AOT 컴파일하고, Vite `transform` 훅에서 컴파일된 JS 를 반환한다. `enforce: "pre"` 로 다른 transform 보다 먼저 동작하며, 컴파일러가 만든 인라인 base64 소스맵을 분리해 Vite 호환 형태(`{ code, map }`)로 넘긴다. `buildEnd` 마다 내부 컴파일러를 폐기해 다음 watch 재빌드 때 재생성하고, watch 변경 파일은 `buildStart` 의 캐시 무효화에 사용한다.
 
-동작: `enforce: "pre"` 플러그인. `buildStart` 에서 내부 `SdTsCompiler`(`output: { js: true, dts: false }`, `includeTests: true`, `rootDir` = cwd)로 패키지 전체를 AOT 컴파일해 소스경로→JS 맵을 만들고, `transform` 훅이 매칭되는 `.ts` 요청에 컴파일된 JS(인라인 소스맵 분리)를 돌려준다. `watchChange` 로 모은 변경 파일을 다음 `buildStart` 의 증분 무효화에 넘기고, `buildEnd` 에서 컴파일러를 폐기해 다음 라운드에 재생성한다. 진단은 logger 로 보고, emit 디스크 출력은 하지 않음.
+- pkg: string — 컴파일 대상 패키지 디렉토리명. `sd.config.ts` 의 `packages` 키와 동일(`@simplysm/` 접두사 제외한 짧은 이름, 예: `"angular"`). 플러그인은 `process.cwd()/packages/<pkg>` 를 컴파일 루트로 잡으므로, 테스트하려는 Angular 패키지명을 그대로 넣는다.
 
-```typescript
+```ts
+// vitest.config.ts
 import { sdAngularPlugin } from "@simplysm/sd-cli";
-// vitest.config.ts project.plugins 에 추가
-plugins: [sdAngularPlugin({ pkg: "angular" })];
+plugins: [sdAngularPlugin({ pkg: "angular" })]
 ```

package/claude/references/sd-simplysm14/apis/sd-cli/SdTsCompiler.md

@@ -1,70 +1,117 @@
 # @simplysm/sd-cli — SdTsCompiler
 
-패키지 디렉토리의 `.ts` 를 TS 또는 Angular AOT 로 **증분** 컴파일하는 클래스. 한 번의 `compileAsync` 호출로 직렬화된 진단 + emit 결과 + lint + SCSS 결과를 묶어 반환. tsconfig 의 `angularCompilerOptions` 존재 여부로 Angular/일반 모드를 자동 판별. 빌드 엔진·`sdAngularPlugin` 내부에서 사용. 진단은 worker 경계를 통과하도록 `SerializedDiagnostic` 으로 직렬화됨.
+패키지 디렉토리의 `.ts` 를 TypeScript 또는 Angular AOT 로 **증분** 컴파일하는 클래스. 한 번의 `compileAsync` 호출로 직렬화된 진단 + emit 결과 + lint + SCSS 결과를 한 묶음(`ISdTsCompilerResult`)으로 반환한다. tsconfig 의 `angularCompilerOptions` 존재 여부로 Angular/일반 모드를 자동 판별. 빌드 엔진과 `sdAngularPlugin` 내부에서 사용. 진단은 worker 경계를 통과하도록 `SerializedDiagnostic` 으로 직렬화되며, 내부 크래시는 단계별로 잡아 진단으로 보고(부분 복구)한다.
 
-## SdTsCompiler
+## ISdTsCompilerOptions (생성자 인자)
+
+```typescript
+interface ISdTsCompilerOptions {
+  pkgDir: string;
+  cwd: string;
+  output: { js: boolean; dts: boolean };
+  includeTests?: boolean;
+  env?: TypecheckEnv;
+  // Angular 전용 (isForAngular 시 활성)
+  sourceFileCache?: AngularSourceFileCache;
+  transformStylesheet?: (data: string, containingFile: string, stylesheetFile?: string) => Promise<string | null>;
+  externalStylesheets?: Map<string, string>;
+  compilerOptionsTransformer?: (options: ts.CompilerOptions) => ts.CompilerOptions;
+  // SCSS/lint 통합
+  lint?: boolean;
+  globalScss?: boolean;
+}
+```
+
+- pkgDir: string — 컴파일 대상 패키지 디렉토리. `<pkgDir>/tsconfig.json` 을 파싱하고 `<pkgDir>/dist` 로 emit, `<pkgDir>/.cache` 에 tsbuildinfo 를 둔다.
+- cwd: string — 워크스페이스 루트. 진단 필터링(`isWorkspaceDiagnostic`)·경로 상대화·에러 포맷 기준점.
+- output.js: boolean — JS emit 여부. true 면 `.js` 산출(non-Angular 은 import 에 `.js` 확장자 부착 + 경로 재작성, Angular 은 `emitResults` 로 반환).
+- output.dts: boolean — `.d.ts` emit 여부. `js`/`dts` 조합에 따라 emit-only·declaration-only·noEmit(둘 다 false = 타입체크만) 으로 분기.
+- includeTests?: boolean — `tests/` 파일을 rootNames 에 포함할지. 기본 false. 테스트까지 컴파일해야 하면 true(예: `sdAngularPlugin`).
+- env?: TypecheckEnv — 타입체크 환경. 지정 시 `getCompilerOptionsForEnv()` 로 환경별 compilerOptions 를 적용하고 tsbuildinfo 파일명에 접미사를 붙임. 환경 분리 타입체크에 쓴다.
+- sourceFileCache?: AngularSourceFileCache — Angular 증분용 SourceFile 캐시. 미제공 시 내부 생성. 여러 `compileAsync` 라운드 간 캐시를 공유하려면 외부에서 주입.
+- transformStylesheet?: (data, containingFile, stylesheetFile?) => Promise<string|null> — 컴포넌트 스타일 변환 콜백(Angular only). `null` 반환 시 변환 안 함. 미제공이고 Angular 면 라이브러리용 SCSS 변환 콜백을 자동 생성. 클라이언트 빌드처럼 커스텀 스타일 파이프라인이 필요할 때 직접 제공.
+- externalStylesheets?: Map<string, string> — 외부 스타일시트 맵(클라이언트 빌드용). 지정 시 비-템플릿 스타일 리소스를 해시 기반 `.css` 외부 파일명으로 매핑(`resourceNameToFileName`). 스타일을 별도 청크로 뽑을 때.
+- compilerOptionsTransformer?: (options) => ts.CompilerOptions — 최종 compilerOptions 후처리 훅. 클라이언트의 `target`/`module`/`rootDir` 강제 등에 쓴다.
+- lint?: boolean — true 면 `compileAsync` 가 program 기반 lint 를 함께 돌려 결과를 `result.lint` 에 담는다(affected 파일만 대상). 컴파일과 동시에 lint 하고 싶을 때.
+- globalScss?: boolean — true 면 `scss/styles.scss` → `dist/styles.css` 글로벌 SCSS 를 컴파일하고 에러를 `result.scssErrors` 에 더한다.
+
+## ISdTsCompilerEmitOptions (compileAsync 2번째 인자)
+
+```typescript
+interface ISdTsCompilerEmitOptions {
+  sourceFilter?: (fileName: string) => boolean;
+  additionalTransformers?: {
+    before?: ts.TransformerFactory<ts.SourceFile>[];
+    after?: ts.TransformerFactory<ts.SourceFile>[];
+  };
+}
+```
+
+- sourceFilter?: (fileName) => boolean — emit 결과 필터(Angular only). true 인 소스만 `emitResults` 에 남긴다. 특정 파일의 emit 만 필요할 때(예: HMR 단일 파일).
+- additionalTransformers?.before / .after — Angular 기본 transformers 앞/뒤에 끼울 추가 TS transformer 배열(Angular only). 커스텀 코드 변환을 주입할 때.
+
+## SdTsCompiler — 메서드
 
 ```typescript
 class SdTsCompiler {
   constructor(options: ISdTsCompilerOptions);
   compileAsync(modifiedFiles?: ReadonlySet<string>, emitOptions?: ISdTsCompilerEmitOptions): Promise<ISdTsCompilerResult>;
+  get sideEffectScssRegistry(): Map<string, SideEffectScssEntry>;
   compileSideEffectScss(): void;
   findAffectedByScss(scssPath: string): string[];
-  get sideEffectScssRegistry(): Map<string, SideEffectScssEntry>;
 }
 ```
 
-- compileAsync(modifiedFiles?, emitOptions?) — 1회 증분 컴파일. `modifiedFiles` = 직전 변경 파일 절대경로 집합(전달 시 sourceFileCache·packageJsonCache 무효화, 미전달 시 전체). `emitOptions` = emit 세부 제어. 위험 구간을 단계별 try/catch 로 감싸 부분 복구하며, 잡힌 크래시는 결과의 `diagnostics`/`errors` 에 합산됨(silent skip 아님).
-- compileSideEffectScss() — `sideEffectScssRegistry` 에 등록된 side-effect SCSS 항목을 모두 CSS 로 컴파일. emit 코드가 항목을 레지스트리에 채운 뒤 호출.
-- findAffectedByScss(scssPath) — 주어진 SCSS 경로에 의존하는 소스 파일 목록 반환(역방향 탐색). watch 에서 SCSS 변경 시 재컴파일 대상을 찾을 때.
-- sideEffectScssRegistry — side-effect SCSS 항목 맵(소스경로 → 엔트리). emit 코드가 항목을 등록하는 통로.
+- compileAsync(modifiedFiles?, emitOptions?) — 1회 증분 컴파일 실행. `modifiedFiles` = 직전 변경된 파일 절대경로 집합(증분 무효화용, 미지정·빈 집합이면 캐시 그대로 사용; node_modules 포함 변경 시 packageJsonCache 클리어). `emitOptions` 는 위 emit 필터/transformer. 같은 인스턴스로 반복 호출해 증분 빌드를 이어간다.
+- sideEffectScssRegistry (getter) — side-effect SCSS 등록부(`Map<소스, SideEffectScssEntry>`) 참조. emit 코드가 항목을 등록하는 통로.
+- compileSideEffectScss() — 위 레지스트리의 모든 항목을 CSS 로 컴파일하고 에러/의존성을 내부 상태에 반영.
+- findAffectedByScss(scssPath) — 주어진 SCSS 경로에 의존하는 소유자 파일 경로 배열을 반환(역방향 탐색). watch 에서 SCSS 변경 시 재컴파일 대상 산출에 쓴다.
 
-`compileAsync` 동작 요약: tsconfig 파싱 → `includeTests` 에 따라 rootNames 결정 → `output` 플래그로 compilerOptions 구성(`compilerOptionsTransformer` 마지막 적용) → Angular 면 `NgtscProgram.analyzeAsync`, 아니면 `EmitAndSemanticDiagnosticsBuilderProgram` → affected 파일 추적 → emit → 진단 수집·직렬화·필터(workspace 내부만) → `globalScss`/`lint` 병렬 실행. 비-Angular emit 은 writeFile 훅으로 디스크에 직접 쓰고(`emitResults` undefined), Angular emit 은 `emitResults` 로 메모리 반환.
+사용 예:
 
 ```typescript
 import { SdTsCompiler } from "@simplysm/sd-cli";
-const compiler = new SdTsCompiler({ pkgDir, cwd, output: { js: true, dts: true }, lint: true });
+
+const compiler = new SdTsCompiler({
+  pkgDir: "/repo/packages/core-common",
+  cwd: "/repo",
+  output: { js: true, dts: true },
+});
 const result = await compiler.compileAsync();
 if (result.errorCount > 0) console.error(result.errors);
+// watch 라운드: 변경 파일만 넘겨 증분 컴파일
+const next = await compiler.compileAsync(new Set(["/repo/packages/core-common/src/foo.ts"]));
 ```
 
-## ISdTsCompilerOptions
-
-생성자 옵션.
-
-- pkgDir: string — 컴파일 대상 패키지 디렉토리 절대경로. rootNames·outDir·SCSS loadPath 기준.
-- cwd: string — workspace 루트. diagnostics 필터링(워크스페이스 내부 진단만 남김)·상대경로 로깅 기준.
-- output: { js: boolean; dts: boolean } — 출력 제어. `js` = `.js` emit 여부, `dts` = `.d.ts` emit 여부. 둘 다 false 면 noEmit(타입체크만). 조합에 따라 declaration/sourceMap/tsBuildInfoFile 이름이 달라짐.
-- includeTests?: boolean — `tests/` 파일을 rootNames 에 포함할지. 기본 false. 테스트 AOT 컴파일(Vitest)에서 true.
-- env?: "node" | "browser" — 타입체크 환경. 설정 시 환경별 compilerOptions 조정(`getCompilerOptionsForEnv`) 적용. 동일 패키지를 환경별로 분리 검증할 때.
-- sourceFileCache?: AngularSourceFileCache — Angular 증분 빌드용 SourceFile 캐시. 미제공 시 내부 생성. 인스턴스 간 캐시 공유로 증분 속도 확보.
-- transformStylesheet?: (data, containingFile, stylesheetFile?) => Promise<string | null> — 스타일시트 변환 콜백(Angular 전용). 인라인/외부 스타일을 가공해 반환, `null` 이면 미변환. 미제공 + Angular 면 라이브러리용 SCSS 변환 콜백이 자동 생성됨.
-- externalStylesheets?: Map<string, string> — 외부 스타일시트 맵(클라이언트 빌드용). `resourceNameToFileName` 에서 비-템플릿 리소스를 해시 기반 `.css` 외부 ID 로 치환할 때 채워짐.
-- compilerOptionsTransformer?: (options) => ts.CompilerOptions — compilerOptions 최종 후처리. 내부 구성 이후 마지막에 적용되어 target/module/rootDir 등을 강제 가능. 클라이언트·Vitest 빌드에서 사용.
-- lint?: boolean — true 면 `compileAsync` 가 lint 를 함께 실행하고 결과를 `result.lint` 에 포함. lint runner 는 lazy init 후 인스턴스 재사용.
-- globalScss?: boolean — true 면 `scss/styles.scss` → `dist/styles.css` 글로벌 SCSS 컴파일 수행. 글로벌 스타일 산출이 필요한 패키지에서.
-
-## ISdTsCompilerEmitOptions
+## ISdTsCompilerResult (compileAsync 반환)
 
-`compileAsync` 의 두 번째 인자(emit 세부 제어, Angular 전용).
-
-- sourceFilter?: (fileName: string) => boolean — emit 대상 소스 필터. 지정 시 통과한 소스의 EmitResult 만 결과에 포함. 일부 파일만 재emit 할 때.
-- additionalTransformers?: { before?; after? } — Angular transformers 외 추가 TS transformer factory. `before`/`after` 각각 `ts.TransformerFactory<ts.SourceFile>[]`. 컴파일 파이프라인에 사용자 변환을 끼울 때.
-
-## ISdTsCompilerResult
-
-`compileAsync` 반환값.
+```typescript
+interface ISdTsCompilerResult {
+  program: ts.Program;
+  builderProgram: ts.EmitAndSemanticDiagnosticsBuilderProgram;
+  isForAngular: boolean;
+  affectedFiles: ReadonlySet<string> | undefined;
+  diagnostics: SerializedDiagnostic[];
+  errorCount: number;
+  warningCount: number;
+  errors?: string[];
+  ngtscProgram?: NgtscProgram;
+  emitResults?: EmitResult[]; // EmitResult: { filename; contents; sourceFileName }
+  lint?: LintWithProgramResult;
+  scssErrors: string[];
+  scssDependencies: ReadonlyMap<string, ReadonlySet<string>>;
+}
+```
 
-- program: ts.Program — TypeScript Program 참조. lint·외부 도구용.
-- builderProgram: ts.EmitAndSemanticDiagnosticsBuilderProgram — Builder Program 참조. 다음 증분 호출에 재사용됨.
-- isForAngular: boolean — Angular 패키지 여부(tsconfig `angularCompilerOptions` 존재로 판별).
-- affectedFiles: ReadonlySet<string> | undefined — 이번 빌드에서 영향받은 파일(posix 경로). `undefined` = 전역 변경(전체 리빌드).
-- diagnostics: SerializedDiagnostic[] — 직렬화된 진단 정보(worker 경계 통과용). 워크스페이스 내부 진단만 남기고 필터됨.
-- errorCount: number — Error 카테고리 진단 수(단계별 크래시 진단 합산).
-- warningCount: number — Warning 카테고리 진단 수.
-- errors?: string[] — Error 진단을 "파일:줄:열: TS코드: 메시지" 형식으로 포맷한 배열. 없으면 undefined.
-- ngtscProgram?: NgtscProgram — NgtscProgram 참조(Angular 전용, HMR 용). 비-Angular 이면 undefined.
-- emitResults?: EmitResult[] — Angular emit 결과 배열(`{ filename, contents, sourceFileName }`). 비-Angular 면 undefined(writeFile 훅이 디스크에 직접 씀).
-- lint?: LintWithProgramResult — lint 결과. `lint` 옵션 활성 시에만 존재.
+- program: ts.Program — TS Program 참조. lint·외부 도구에 넘길 때.
+- builderProgram — 증분 BuilderProgram 참조.
+- isForAngular: boolean — Angular 모드로 컴파일됐는지(tsconfig 의 `angularCompilerOptions` 유무로 결정). 후속 처리 분기에 쓴다.
+- affectedFiles: ReadonlySet<string> | undefined — 이번 빌드에서 영향받은 파일(posix 경로). `undefined` = 전역 변경(전체 리빌드). 부분 재처리 범위 판단에 쓴다.
+- diagnostics: SerializedDiagnostic[] — 직렬화된 진단 전체(worker 경계 통과용). 내부 크래시 진단도 합산됨.
+- errorCount / warningCount: number — Error / Warning 카테고리 진단 수. 크래시는 errorCount 에 가산.
+- errors?: string[] — Error 진단을 `"파일:줄:열: TS코드: 메시지"` 형식으로 포맷한 배열(없으면 undefined). 로그 출력에 바로 쓴다.
+- ngtscProgram?: NgtscProgram — NgtscProgram 참조(Angular only, HMR 용). non-Angular 이면 undefined.
+- emitResults?: EmitResult[] — Angular emit 결과 배열. 각 항목 `{ filename; contents; sourceFileName }`(sourceFileName = 원본 소스 경로). non-Angular 은 writeFile 훅으로 디스크에 직접 쓰므로 undefined. 메모리상 컴파일 결과가 필요한 플러그인이 소비.
+- lint?: LintWithProgramResult — lint 결과(`lint: true` 일 때만).
 - scssErrors: string[] — SCSS 컴파일 에러 목록.
 - scssDependencies: ReadonlyMap<string, ReadonlySet<string>> — SCSS 의존성 맵(소유자 파일 → 의존 SCSS 경로 집합). watch 역방향 탐색용.