@simplysm/sd-claude 14.0.88 → 14.0.90

package/claude/references/sd-simplysm14/apis/excel/wrapper.md

@@ -1,18 +1,42 @@
 # @simplysm/excel — ExcelWrapper
 
-Zod 스키마 1개로 레코드 배열 ↔ Excel 파일을 타입 안전하게 매핑할 때 읽는다. 스키마 각 필드의 `.describe()` 가 Excel 헤더(표시명)가 되고, 필드 타입으로 읽기 시 값 변환·검증을 수행한다. 저수준 셀 조작 없이 "정형 데이터의 import/export" 용도일 때 사용.
+Zod 스키마로 엑셀 헤더 ↔ 필드 매핑, 셀 값 타입 변환, 행 단위 유효성 검사를 자동화해 "레코드 배열 ↔ 엑셀" 변환을 한 번에 처리할 때 쓰는 고수준 래퍼. 헤더 텍스트는 각 필드의 `.describe()` 로 지정하며, 미지정 필드는 키 이름을 헤더로 쓴다. 표준 입력 양식 업로드/다운로드 같은 정형 변환에 적합.
 
-## 시그니처
+## 생성자
 
 ```typescript
 new ExcelWrapper<TSchema extends z.ZodObject<z.ZodRawShape>>(schema: TSchema)
+```
+
+- `schema: TSchema` — 레코드 구조를 정의하는 Zod 객체 스키마. 각 필드에 `.describe("헤더이름")` 으로 엑셀 헤더 표시명을 지정한다. optional/nullable/default/boolean 여부가 읽기 기본값·필수 강조·타입 변환 동작을 결정한다.
+
+## read
 
+```typescript
 read(
   file: Bytes | Blob,
   wsNameOrIndex: string | number = 0,
   options?: { excludes?: (keyof z.infer<TSchema>)[] },
 ): Promise<z.infer<TSchema>[]>
+```
+
+- `file: Bytes | Blob` — 읽을 .xlsx 데이터.
+- `wsNameOrIndex: string | number` — 읽을 시트 이름 또는 0 기반 인덱스. 기본 `0`(첫 시트).
+- `options.excludes?: (keyof Schema)[]` — 매핑에서 제외할 필드 키 배열. 해당 헤더는 읽지 않음.
+
+동작: 스키마 표시명 집합에 해당하는 헤더만 골라 데이터 테이블을 읽고, 각 행을 필드 키로 역매핑한 뒤 값 변환 → Zod `safeParse` 검증한다. 빈/누락 값은 스키마 기본값 규칙(아래)으로 채우고, 한 행의 모든 매핑 값이 비면 그 행은 건너뛴다. 데이터가 0건이거나 검증 실패면 시트명을 포함해 throw(부분 반영 없이 전체 중단). 워크북은 내부에서 열고 finally 로 닫는다.
+
+값 변환 규칙:
+
+- `ZodString` → 문자열(비문자열은 `String()`).
+- `ZodNumber` → `num.parseFloat`.
+- `ZodBoolean` → `"1"`/`"true"`→`true`, `"0"`/`"false"`→`false`, 그 외 `Boolean()`.
+- `DateOnly`/`DateTime`/`Time` 인스턴스 → 그대로 보존.
+- 빈/누락 값(`null`/`""`) → 스키마 기본값: `ZodDefault` 면 그 기본값, optional/nullable 면 `undefined`, 필수 boolean 이면 `false`, 그 외 `undefined`.
 
+## write
+
+```typescript
 write(
   wsName: string,
   records: Partial<z.infer<TSchema>>[],
@@ -20,56 +44,29 @@ write(
 ): Promise<ExcelWorkbook>
 ```
 
-- `schema: z.ZodObject` — 레코드 구조. 각 필드의 `.describe("표시명")` 이 Excel 헤더명. 미지정 시 필드 키를 헤더로 사용.
-- `read.file: Bytes | Blob` — 읽을 .xlsx 데이터.
-- `read.wsNameOrIndex: string | number` — 대상 시트(기본 0번). 이름 또는 0 기반 인덱스.
-- `read.options.excludes?: (keyof ...)[]` — 매핑에서 제외할 필드 키 목록.
-- `write.wsName: string` — 생성할 시트 이름.
-- `write.records: Partial<...>[]` — 기록할 부분 레코드 배열. 누락 필드는 빈 셀.
-- `write.options.excludes?: (keyof ...)[]` — 출력에서 제외할 필드 키 목록.
-
-## read 동작
-
-- 헤더명↔필드 역매핑 후 `ws.getDataTable({ usableHeaderNameFn })` 로 표시명에 일치하는 컬럼만 추출.
-- 각 셀 값을 필드 타입별로 변환 후, 행마다 `schema.safeParse` 로 검증. 실패하면 그 행에서 throw(부분 반영 없음).
-- 모든 필드가 null/`""` 인 행은 skip.
-- 데이터가 한 건도 없으면 기대 헤더 목록을 담은 메시지로 throw.
-- 내부에서 워크북을 열고 `finally` 로 `close()` 하므로 호출자 정리 불필요.
+- `wsName: string` — 만들 시트 이름.
+- `records: Partial<Schema>[]` — 출력할 레코드 배열(부분 객체 허용 — 누락 키는 빈 셀).
+- `options.excludes?: (keyof Schema)[]` — 출력에서 제외할 필드 키 배열.
 
-### 값 변환 규칙
-
-- 빈값(null/`""`) → 스키마 기본값: `ZodDefault` 면 그 기본값, optional/nullable 이면 `undefined`, 필수 boolean 이면 `false`, 그 외 `undefined`.
-- `ZodString` → 문자열(아니면 `String()` 캐스팅).
-- `ZodNumber` → number(문자열은 `num.parseFloat`).
-- `ZodBoolean` → `"1"`/`"true"` → `true`, `"0"`/`"false"` → `false`, 그 외 `Boolean()`.
-- `DateOnly`/`DateTime`/`Time` 인스턴스는 그대로 통과.
-
-## write 동작
-
-- 0행에 헤더(제외 후 필드 순서), 1행부터 레코드 값 기록.
-- 전 셀에 4변 테두리 적용.
-- **필수**(optional/nullable/default 아님)이며 boolean 이 아닌 필드의 헤더 셀은 노란색(`00FFFF00`) 강조.
-- zoom 85%, 0행 틀고정 적용.
-- 반환된 `ExcelWorkbook` 의 리소스 관리는 **호출자 책임** — 사용 후 `close()` 필수. write 중 예외 발생 시 내부에서 close 후 rethrow.
+동작: 새 워크북에 시트 1개를 만들고, 0행에 표시명 헤더, 1행부터 각 레코드 값을 스키마 키 순서대로 쓴다. 전체 표에 4변 테두리, 필수(non-optional·non-nullable·non-default)이며 boolean 이 아닌 필드의 헤더 셀에 노란 배경(`"00FFFF00"`) 강조, zoom 85%, 0행 틀고정을 적용한다. **반환된 워크북의 close 는 호출자 책임** — 사용 후 반드시 `close()`.
 
 ## 사용 예
 
 ```typescript
-import { z } from "zod";
-
 const schema = z.object({
-  name: z.string().describe("이름"),
-  age: z.number().optional().describe("나이"),
+  code: z.string().describe("코드"),
+  qty: z.number().describe("수량"),
+  note: z.string().optional().describe("비고"),
 });
 const wrapper = new ExcelWrapper(schema);
 
-// 읽기 ("이름"/"나이" 헤더를 0번 시트에서 매칭)
-const rows = await wrapper.read(bytes);
+// 읽기
+const records = await wrapper.read(bytes, "입력", { excludes: ["note"] });
 
-// 쓰기 (호출자가 close 책임)
-const wb = await wrapper.write("회원", [{ name: "홍길동", age: 30 }]);
+// 쓰기 (워크북 close 는 호출자 책임)
+const wb = await wrapper.write("결과", records);
 try {
-  const out = await wb.toBytes();
+  const bytes = await wb.toBytes();
 } finally {
   await wb.close();
 }
@@ -77,7 +74,7 @@ try {
 
 ## 주의사항
 
-- `.describe()` 표시명이 실제 Excel 헤더와 일치해야 `read` 가 컬럼을 인식. 일치 헤더가 전혀 없으면 데이터 0건으로 throw.
-- 표시명 미지정 필드는 필드 키 그대로 헤더로 쓰이므로, 한글 헤더가 필요하면 반드시 `.describe()` 지정.
-- `read` 행 검증은 전부-성공 전제: 한 행이라도 `safeParse` 실패 시 전체 throw.
-- `write` 반환 워크북 미`close` 시 리소스 누수.
+- 헤더 매핑은 `.describe()` 값(미지정 시 키)이 엑셀 헤더 텍스트와 정확히 일치해야 한다. 매핑되는 헤더가 한 행 내 중복이거나 데이터가 0건이면 throw.
+- `read` 는 행 단위 Zod 검증을 거치므로, 한 행이라도 스키마 위반이면 전체가 throw(부분 결과 없음).
+- `write` 의 필수 헤더 노랑 강조는 "필수 입력 칸" 안내 목적 — optional/nullable/default 또는 boolean 필드는 강조되지 않는다.
+- 결측 보존: optional/nullable 필드의 빈 값은 `undefined` 로 유지된다(임의 치환 없음). 필수 boolean 만 `false` 로 채워진다.

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

@@ -1,43 +1,49 @@
 # @simplysm/lint
 
-심플리즘 워크스페이스 전용 ESLint 플러그인. 커스텀 규칙 9종 묶음(`eslint-plugin`)과, 그 규칙들을 포함해 JS/TS/HTML 파일별로 완성된 flat config 배열(`eslint-recommended`)을 서브패스 export 로 제공. `src/index.ts` 없음 — `package.json` 의 `exports`(`./eslint-plugin`, `./eslint-recommended`)가 진입점.
+simplysm 전용 ESLint 9 flat-config 프리셋과 커스텀 규칙 9종을 제공하는 ESLint 플러그인 패키지. `src/index.ts` 없음 — `package.json` 의 `exports`(`./eslint-plugin`, `./eslint-recommended`) 두 subpath 가 진입점. 패키지 루트 import 는 없음.
 
 ## 사용 트리거 인덱스
 
-- **eslint-recommended** — 프로젝트 `eslint.config.{js,mjs,cjs}` 에서 simplysm 표준 lint 규칙 전체(JS/TS/HTML 파일별 + tseslint/angular-eslint 통합)를 한 번에 적용할 때 import 하는 default export(완성된 flat config 배열).
-- **eslint-plugin** — `@simplysm/<rule>` 커스텀 규칙 9종을 직접 켜거나, 개별 규칙의 감지 범위·메시지·autofix·옵션을 파악할 때. 자세히: [rules.md](./rules.md)
+- **eslint-recommended** (`@simplysm/lint/eslint-recommended`) — 프로젝트 `eslint.config.ts` 에서 통째로 spread 해 쓰는 완성형 flat-config 배열. JS/TS/HTML 파일별 규칙·ignore·플러그인·Angular 통합이 모두 포함됨. 새 프로젝트 lint 설정을 잡을 때.
+- **eslint-plugin** (`@simplysm/lint/eslint-plugin`) — 커스텀 규칙만 담은 ESLint Plugin 객체(`{ rules }`). recommended 를 쓰지 않고 규칙을 직접 골라 등록할 때, 또는 규칙 동작을 개별 검토할 때. 자세히: [rules.md](./rules.md)
 
 ## eslint-recommended
 
-`@simplysm/lint/eslint-recommended` 의 default export. `tseslint.config(...)` 결과(`FlatConfig` 배열)이므로 호출형이 아니라 완성된 상수. 그대로 export 하거나 spread 후 항목을 덧붙여 사용.
+`@simplysm/lint/eslint-recommended` 의 default export. `typescript-eslint` 의 `tseslint.config(...)` 결과 = flat-config 객체 배열. 그대로 spread 해서 사용함.
 
-```js
-// eslint.config.js
+```typescript
+// eslint.config.ts
 import recommended from "@simplysm/lint/eslint-recommended";
-export default recommended;
-// 규칙 추가 시: export default [...recommended, { files: ["**/*.ts"], rules: { "no-debugger": "error" } }];
+
+export default [...recommended];
 ```
 
-config 가 강제하는 핵심 내용(파일 glob 블록별):
+배열을 구성하는 config 블록(순서대로):
 
-- **ignores** — `**/node_modules/**`, `**/dist/**`, `**/.*/**`(숨김 디렉터리 전체). 순회 자체를 건너뜀.
-- **`**/*.{js,mjs,cjs}`** — node globals 적용. 켜는 규칙: `require-await`(async 함수에 await 없으면 오류), `no-shadow`(상위 스코프 변수 가림 금지), `no-duplicate-imports`(같은 모듈 중복 import 금지), `no-unused-expressions`(부수효과 없는 표현식 금지), `no-undef`(선언 안 된 식별자 사용 금지), `unused-imports/no-unused-imports`(미사용 import 제거, autofix), `unused-imports/no-unused-vars`(미사용 변수·인자 경고, `^_` 접두는 무시), `import/no-extraneous-dependencies`(미선언 의존성 import 금지, 단 `lib/**`·`eslint.config.*`·`simplysm.*`·`vitest.config.*` 는 devDependencies 허용), `@simplysm/no-subpath-imports-from-simplysm`, `@simplysm/no-hard-private` + 아래 공통 규칙군.
-- **`**/*.ts`** — `angular.configs.tsRecommended` 를 펼친 뒤 추가. `processInlineTemplates` 로 인라인 템플릿 분리, `tseslint.parser`(`parserOptions.project: true`) 사용, `eslint-import-resolver-typescript` resolver 를 `import.meta.resolve` 로 자동 등록. 켜는 규칙: `no-console`(error), 그리고 타입 인식 `@typescript-eslint/*` 규칙 — `require-await`, `await-thenable`(thenable 만 await), `return-await`(`in-try-catch` = try/catch 안에서만 return await 요구), `no-floating-promises`(await/void 안 한 Promise 금지), `no-shadow`, `no-unnecessary-condition`(`allowConstantLoopConditions: true` = 상수 루프 조건 허용), `no-unnecessary-type-assertion`, `prefer-reduce-type-parameter`, `prefer-return-this-type`, `no-unused-expressions`, `strict-boolean-expressions`(`allowNullableBoolean`·`allowNullableObject` = nullable boolean/object 의 조건식 허용), `ban-ts-comment`(`ts-expect-error` 는 3자 이상 설명 필수), `prefer-readonly`, `naming-convention`(private 멤버는 `_` 접두 필수, 그 외 포맷 제약 없음), `no-misused-promises`(`checksVoidReturn.arguments:false`·`inheritedMethods:false` = 콜백 인자·상속 메서드의 void 반환 검사는 끔), `only-throw-error`(Error 외 throw 금지), `no-array-delete`(배열에 `delete` 금지). 커스텀 규칙 6종: `@simplysm/ng-no-async-effect`, `no-hard-private`, `no-subpath-imports-from-simplysm`, `ts-no-throw-not-implemented-error`(warn), `ts-no-unused-injects`, `ts-no-unused-protected-readonly`. + `@angular-eslint/no-output-native`(off).
-- **`**/*.html`** — `angular.configs.templateRecommended` + `templateAccessibility` 확장. 커스텀 템플릿 규칙: `@simplysm/ng-template-no-strict-null-check`, `ng-template-no-todo-comments`(warn), `ng-template-sd-require-binding-attrs` + `@angular-eslint/template/eqeqeq`(`allowNullOrUndefined: true` = null/undefined 비교는 느슨한 비교 허용), `label-has-associated-control`(off), `no-any`(error).
-- **`**/tests/**/*.ts`(override)** — 테스트 완화: `no-console`(off), `import/no-extraneous-dependencies`(off), `@simplysm/ts-no-throw-not-implemented-error`(off).
-- **`**/vitest.config.ts`(override)** — `no-restricted-properties`(off). 설정 파일에서 `process.env` 직접 접근 허용.
+- **globalIgnores** — `**/node_modules/**`, `**/dist/**`, `**/.*/**` 순회 자체를 건너뜀. 점(.)으로 시작하는 디렉토리 전체가 제외 대상.
+- **공통 languageOptions** — `ecmaVersion: "latest"`, `sourceType: "module"`.
+- **JS 블록** (`**/*.js`, `**/*.mjs`, `**/*.cjs`) — node 글로벌, `import`/`@simplysm`/`unused-imports` 플러그인 등록. 활성 규칙: `require-await`, `no-shadow`, `no-duplicate-imports`, `no-unused-expressions`, `no-undef`, unused-imports 2종, `import/no-extraneous-dependencies`(lib·`eslint.config`·`simplysm`·`vitest.config` 파일은 devDeps 허용), `@simplysm/no-subpath-imports-from-simplysm`, `@simplysm/no-hard-private`, node 빌트인 차단 규칙군, env 직접접근 차단 규칙군.
+- **angular tsRecommended** — `angular.configs.tsRecommended` spread.
+- **TS 블록** (`**/*.ts`) — `processor: angular.processInlineTemplates`(인라인 템플릿 추출 후 별도 lint), `parserOptions.project: true`(타입 정보 사용), `import/resolver` 로 typescript resolver(`alwaysTryTypes: true`) 지정. typescript-eslint 타입체크 규칙 다수 + `@simplysm` 커스텀 규칙 6종 활성. 커스텀 규칙 심각도: `ng-no-async-effect`/`no-hard-private`/`no-subpath-imports-from-simplysm`/`ts-no-unused-injects`/`ts-no-unused-protected-readonly` = `error`, `ts-no-throw-not-implemented-error` = `warn`. `@angular-eslint/no-output-native` 은 `off`.
+- **HTML 블록** (`**/*.html`) — `angular.configs.templateRecommended` + `templateAccessibility` extends. `@simplysm` 템플릿 규칙 3종 활성: `ng-template-no-strict-null-check`=`error`, `ng-template-no-todo-comments`=`warn`, `ng-template-sd-require-binding-attrs`=`error`. `@angular-eslint/template/eqeqeq` 는 `allowNullOrUndefined: true`, `label-has-associated-control`=`off`, `no-any`=`error`.
+- **테스트 오버라이드** (`**/tests/**/*.ts`) — 테스트 코드 완화: `no-console`=`off`, `import/no-extraneous-dependencies`=`off`, `@simplysm/ts-no-throw-not-implemented-error`=`off`.
+- **vitest.config 오버라이드** (`**/vitest.config.ts`) — `no-restricted-properties`=`off` (설정 파일에서 `process.env` 접근 허용).
 
-공통 규칙군(JS/TS 양쪽 적용): `no-warning-comments`(warn, TODO/FIXME 등 경고), `eqeqeq`(`always`, 단 `null` 비교는 `==`/`!=` 허용), `no-self-compare`, `array-callback-return`(map/filter 등 콜백에 return 강제). 추가 공통 금지: `no-restricted-globals`(`Buffer` 전역 금지 → `Uint8Array`/`BytesUtils`), `no-restricted-imports`(`buffer`·`events`·`eventemitter3` 모듈 금지), `no-restricted-properties`(`process.env` 직접 접근 금지 → `env("...")`), `no-restricted-syntax`(`import.meta.env` 직접 접근·`env("NODE_ENV")`·`=== undefined`/`!== undefined` 류 strict 비교 금지 → `== null`/`!= null`).
+주의:
 
-주의: 타입 인식 `@typescript-eslint` 규칙이 켜져 있어 TS 파일은 `parserOptions.project: true` 가 동작하는 환경(tsconfig 포함)이어야 함.
+- TS 블록은 타입 정보(`parserOptions.project: true`)를 요구하므로, 대상 프로젝트에 유효한 `tsconfig` 가 있어야 함.
+- node 빌트인 차단(`noNodeBuiltinsRules`): `Buffer` 글로벌 및 `buffer`/`events`/`eventemitter3` import 금지 — 각각 `Uint8Array`/`@simplysm/core-common`의 `BytesUtils`·`EventEmitter` 로 대체 유도. JS·TS 블록 모두에 적용.
+- env 직접접근 차단(`noDirectEnvAccessRules`): `process.env`·`import.meta.env` 직접 접근, `env("NODE_ENV")` 호출, `=== undefined`/`!== undefined`(엄격 비교) 를 `no-restricted-properties`/`no-restricted-syntax` 로 막음(엄격 비교는 `== null`/`!= null` 로 유도). JS·TS 블록 모두에 적용.
 
 ## eslint-plugin
 
-`@simplysm/lint/eslint-plugin` 의 default export 는 `{ rules: { ... } }` 형태의 ESLint 플러그인 객체. 9개 규칙을 규칙 ID → 규칙 정의로 매핑. 보통 `eslint-recommended` 가 내부에서 `@simplysm` 네임스페이스로 등록하므로, 직접 import 는 recommended 없이 커스텀 config 를 짜거나 특정 규칙만 개별 제어할 때만 필요. 규칙별 상세는 [rules.md](./rules.md).
+`@simplysm/lint/eslint-plugin` 의 default export. ESLint Plugin 형태 객체.
 
-```js
+```typescript
 import plugin from "@simplysm/lint/eslint-plugin";
-export default [{ plugins: { "@simplysm": plugin }, rules: { "@simplysm/no-hard-private": "error" } }];
+// plugin === { rules: { "ng-no-async-effect": ..., "no-hard-private": ..., ... } }
 ```
 
-규칙 ID 9종: `ng-no-async-effect`, `ng-template-no-strict-null-check`, `ng-template-no-todo-comments`, `ng-template-sd-require-binding-attrs`, `no-hard-private`, `no-subpath-imports-from-simplysm`, `ts-no-throw-not-implemented-error`, `ts-no-unused-injects`, `ts-no-unused-protected-readonly`.
+- `rules` — 규칙 id → 규칙 객체 맵. 등록된 9개 id: `ng-no-async-effect`, `ng-template-no-strict-null-check`, `ng-template-no-todo-comments`, `ng-template-sd-require-binding-attrs`, `no-hard-private`, `no-subpath-imports-from-simplysm`, `ts-no-throw-not-implemented-error`, `ts-no-unused-injects`, `ts-no-unused-protected-readonly`.
+
+flat-config 에서 직접 등록할 때는 `plugins: { "@simplysm": plugin }` 로 매핑 후 `"@simplysm/<id>"` 로 켬. 각 규칙의 검사 대상·옵션·autofix·메시지는 [rules.md](./rules.md) 참조.

package/claude/references/sd-simplysm14/apis/lint/rules.md

@@ -1,90 +1,130 @@
 # @simplysm/lint — rules
 
-`eslint-plugin` 이 노출하는 커스텀 ESLint 규칙 9종. 규칙 ID 는 등록 시 `@simplysm/<name>`. 개별 규칙을 켜거나 lint 위반 메시지·autofix·옵션 의미를 파악할 때 읽음. 옵션 없는 규칙은 `schema: []`. autofix 는 `fixable: "code"` 표시 규칙만 제공. 모든 규칙은 `createRule`(= `ESLintUtils.RuleCreator`)로 생성되어 문서 URL 이 자동 부여됨.
+`eslint-plugin` 이 노출하는 커스텀 ESLint 규칙 9종. 규칙 id 는 등록 시 `@simplysm/<name>`. 개별 규칙을 켜거나 lint 위반 메시지·autofix·옵션 의미를 파악할 때 읽음. 모든 규칙은 `createRule`(= `ESLintUtils.RuleCreator`, `src/utils/create-rule.ts`)로 생성되어 문서 URL 이 자동 부여됨. 옵션 없는 규칙은 `schema: []`. autofix 는 아래 "autofix" 표기 규칙만 제공.
 
-## ng-no-async-effect
+## no-hard-private
 
-`type: problem`, autofix 없음. `@angular/core` 의 `effect()` 첫 인자로 async 함수(화살표/함수표현식이며 `async` 플래그)를 직접 전달하는 것을 금지. `await` 이후 읽은 signal 이 반응형 컨텍스트를 벗어나 의존성 추적에서 빠지는 버그, 그리고 반환값이 `Promise<void>` 가 되어 cleanup 등록이 막히는 문제를 방지.
+ECMAScript hard private(`#field`) 사용을 금지하고 TypeScript `private _` 스타일을 강제. `type: "problem"`, autofix 있음, 옵션 없음. JS·TS 양쪽에서 동작.
 
-- 감지 범위: named import(`effect`), aliased import(`effect as ngEffect`), namespace import(`ng.effect(...)`). `@angular/core` 가 아닌 모듈·로컬 선언 `effect` 는 무시(스코프·import 정의를 추적해 판별).
-- `noAsyncEffect` — async 직접 전달 금지 메시지. 비동기 작업은 `void untracked(async () => { ... })` 안에서 수행하라고 안내.
+검사 대상: 클래스 필드 선언(`#field`), 메서드 선언(`#method()`), 접근자 선언(`accessor #field`), 멤버 접근 표현식(`this.#field`).
 
-```ts
-// 위반
-effect(async () => { await load(); });
-// 권장
-effect(() => { sig(); void untracked(async () => { await load(); }); });
+메시지:
+- `preferSoftPrivate` — hard private(#) 금지, `private _` 스타일 사용 안내. autofix 는 `#name` → `_name` 으로 치환하고, 선언부에 접근제어자가 없으면 `private ` 를 앞에 삽입(데코레이터·`static`·`async`·`readonly` 순서를 보존해 그 뒤 삽입). 토큰 계산 실패 시 이름만 바뀌는 불완전 수정을 막기 위해 수정 전체를 건너뜀.
+- `nameConflict` — `#{{name}}` 을 `_{{name}}` 으로 바꿀 수 없음(동일 이름 멤버가 클래스에 이미 존재). 이 경우 보고만 하고 autofix 안 함. 중첩 클래스는 스택으로 각 클래스 멤버 집합을 관리.
+
+```typescript
+class A { #count = 0; inc() { this.#count++; } }
+// → private _count = 0; inc() { this._count++; }
 ```
 
-## no-hard-private
+## no-subpath-imports-from-simplysm
 
-`type: problem`, autofix 있음. ECMAScript hard private(`#field`) 금지, TypeScript `private _` 스타일 강제.
+`@simplysm/*` 패키지의 `src` 하위 경로 import 를 금지(빌드 산출물 export 경유를 강제). `type: "problem"`, autofix 있음, 옵션 없음. JS·TS 양쪽에서 동작.
 
-- 감지: 필드 선언 `#field`, 메서드 선언 `#method()`, 접근자 선언 `accessor #field`, 사용처 `this.#field`. 중첩 클래스도 스택으로 추적.
-- autofix: `#a` → `_a` 이름 변경 + 선언부 앞에 `private ` 삽입(데코레이터·`static`·`async`·`readonly` 순서 보존; 사용처 `this.#a` → `this._a`). 단, 같은 클래스에 `_a` 멤버가 이미 있으면 충돌로 변환 불가 → 보고만 하고 autofix 안 함.
-- `preferSoftPrivate` — hard private 금지(이름 변경 가능 시 적용되는 일반 메시지).
-- `nameConflict` — `_{{name}}` 멤버가 이미 존재해 변환 불가. `{{name}}` 치환.
+검사 대상: 정적 import(`import ... from`), 동적 import(`import("...")`), 재내보내기(`export { x } from`), 전체 재내보내기(`export * from`). import 경로를 `/` 로 분리해 3번째 세그먼트가 `src` 인 경우(`@simplysm/pkg/src`, `@simplysm/pkg/src/xxx`)만 위반. `@simplysm/pkg`·`@simplysm/pkg/xxx`(src 가 아닌 subpath)는 허용.
 
-## no-subpath-imports-from-simplysm
+메시지:
+- `noSubpathImport` — `'@simplysm/{{pkg}}'` 에서 `src` 하위 경로 import 불가. autofix 는 경로를 `@simplysm/<pkg>`(원래 따옴표 유지)로 치환.
+
+```typescript
+import { x } from "@simplysm/core-common/src/x"; // → "@simplysm/core-common"
+```
+
+## ng-no-async-effect
+
+Angular `@angular/core` 의 `effect()` 에 async 함수를 직접 전달하는 것을 금지. `type: "problem"`, autofix 없음, 옵션 없음. `await` 이후 signal read 가 reactive 의존성으로 추적되지 않고 반환값이 `Promise<void>` 가 되어 cleanup 등록이 막히는 문제 방지.
 
-`type: problem`, autofix 있음. `@simplysm/<pkg>/src/...` 형태의 `src` 하위 경로 import 금지(`@simplysm/<pkg>` 및 `src` 가 아닌 하위 경로는 허용).
+검사 대상: `effect(...)` 호출의 첫 인자가 async ArrowFunction/FunctionExpression 인 경우. `effect` 식별자가 `@angular/core` 에서 import 되었는지 스코프로 검증 — named(`import { effect }`)·aliased(`effect as ngEffect`)·namespace(`import * as ng` → `ng.effect(...)`) import 만 인정. 다른 모듈 또는 로컬 선언 `effect` 는 무시.
 
-- 감지: 정적 `import ... from '...'`, 동적 `import('...')`, 재내보내기 `export { ... } from '...'`, 전체 재내보내기 `export * from '...'`. 경로를 `/` 로 분해해 3번째 세그먼트가 `src` 인 경우만 위반.
-- autofix: `@simplysm/pkg/src/x` → `@simplysm/pkg` 로 치환(원본 따옴표 종류 유지).
-- `noSubpathImport` — `{{pkg}}`(패키지명)·`{{importPath}}`(원본 경로) 치환.
+메시지:
+- `noAsyncEffect` — async 함수 직접 전달 금지. 비동기는 `void untracked(async () => { ... })` 내부에서 수행하라고 안내. 보고 위치는 첫 인자(콜백) 노드.
+
+```typescript
+effect(() => { this.sig(); void untracked(async () => { await this.load(); }); });
+```
 
 ## ts-no-throw-not-implemented-error
 
-`type: suggestion`, autofix 없음, recommended 에서 `warn`(테스트에서는 off). `@simplysm/core-common` 의 `NotImplementedError` 를 `new` 로 생성하는 코드를 감지해 미구현 코드의 프로덕션 유입을 경고.
+`@simplysm/core-common` 의 `NotImplementedError` 를 `new` 로 인스턴스화하는 코드를 감지(미구현 코드의 프로덕션 유입 방지). `type: "suggestion"`, autofix 없음, 옵션 없음. recommended 에서 `warn`(테스트 파일은 `off`).
+
+검사 대상: `new NotImplementedError(...)`(named/aliased import), `new CC.NotImplementedError(...)`(namespace import). 식별자가 `@simplysm/core-common` 에서 import 되었는지 스코프로 검증. 동적 import(`await import(...)`)는 감지 안 함.
 
-- 감지: named/aliased import(`NotImplementedError`, `NotImplementedError as NIE`), namespace import(`new CC.NotImplementedError()`). import 소스가 `@simplysm/core-common` 인지 스코프로 검증. 동적 import 는 무시.
-- `noThrowNotImplementedError` — `{{text}}` 치환. `new` 첫 인자가 비어있지 않은 문자열 리터럴이면 그 문자열을, 아니면 `"미구현"` 을 그대로 출력.
+메시지:
+- `noThrowNotImplementedError` — 메시지 본문은 `{{text}}` 치환. 첫 인자가 비어있지 않은 문자열 리터럴이면 그 값을, 아니면 `"미구현"` 을 출력.
 
-```ts
-throw new NotImplementedError("결제 모듈 미구현"); // → "결제 모듈 미구현" 경고
+```typescript
+import { NotImplementedError } from "@simplysm/core-common";
+new NotImplementedError("결제 연동"); // → "결제 연동" 경고
 ```
 
 ## ts-no-unused-injects
 
-`type: problem`, autofix 있음. 클래스 내 `inject()` 호출로 초기화된 프로퍼티 중 같은 클래스 어디에서도 참조되지 않는 필드를 보고.
+미사용 Angular `inject()` 필드를 감지. `type: "problem"`, autofix 있음, 옵션 없음.
 
-- 감지: `PropertyDefinition` 의 값이 `inject(...)` 호출이고 key 가 식별자인 필드. 클래스 본문 전체를 재귀 순회해 필드명과 동일한 식별자(자기 key 제외)가 하나도 없으면 미사용으로 판정.
-- autofix: 해당 필드 제거(앞 토큰 끝 ~ 뒤 토큰 사이 range 삭제).
-- `unusedInject` — `inject() field "{{name}}" is never used.`
+검사 대상: 클래스 본문에서 `inject(...)` 호출로 초기화된 PropertyDefinition(키가 Identifier). 같은 클래스 본문 전체를 순회해 필드명과 동일한 Identifier 참조(필드 키 자신 제외)가 0개면 미사용으로 판정. 클래스 내부 참조만 검사 — 템플릿 사용 여부는 보지 않음.
+
+메시지:
+- `unusedInject` — `inject() field "{{name}}" is never used.` autofix 는 해당 필드 선언을 앞 토큰 끝부터 제거(뒤 토큰이 있으면 필드 끝까지).
+
+```typescript
+class C { private _svc = inject(MyService); } // _svc 미참조 시 제거
+```
 
 ## ts-no-unused-protected-readonly
 
-`type: problem`, autofix 있음. `@Component` 데코레이터가 달린 클래스에서 `protected readonly`(non-static) 필드가 인라인 `template` 과 클래스 본문 어디에서도 참조되지 않으면 보고.
+Angular `@Component` 의 인라인 템플릿·클래스 본문 어디에서도 안 쓰이는 `protected readonly` 필드를 감지. `type: "problem"`, autofix 있음, 옵션 없음.
+
+검사 대상: `@Component` 데코레이터가 있고 그 첫 인자 객체에 `template` 속성(문자열 리터럴 또는 템플릿 리터럴)이 있는 클래스. 그 클래스의 `protected readonly` 비-static 필드(키가 Identifier)가 ① 인라인 템플릿에서 미참조 ② 클래스 본문 다른 멤버에서 미참조 둘 다일 때 보고. 템플릿 식별자는 `@angular/compiler` 의 `parseTemplate` 으로 AST 파싱 후 `ImplicitReceiver`/`ThisReceiver` 위 `PropertyRead`(클래스 필드 참조)만 수집하며, `*ngFor` 로컬·`@let`·`@if ... as`·`@for` item/별칭 등 스코프 로컬 변수는 제외. `@if`/`@switch`/`@for`/`@defer` 블록, 입력/이벤트/구조 디렉티브 바인딩까지 순회. `templateUrl`(외부 템플릿)은 대상 아님(`template` 문자열만).
 
-- 동작: `@Component({ template: ... })` 의 인라인 템플릿 문자열(템플릿 리터럴/문자열 리터럴)을 `@angular/compiler` 의 `parseTemplate` 으로 파싱해 바인딩 식별자를 수집. `@for` item·context 변수, `@if (...; as alias)`, `@let` 선언, 구조 디렉티브(`*ngFor` 등) 로컬 변수는 스코프에서 제외(오탐 방지). 템플릿·클래스 양쪽 모두 미사용일 때만 보고. `template` prop 이 없거나 빈 문자열이면 검사하지 않음(외부 `templateUrl` 미지원).
-- autofix: 필드 선언 라인 제거(앞 들여쓰기·뒤 세미콜론/개행 포함).
-- `unusedField` — `Protected readonly field "{{name}}" is not used in class or template.`
+메시지:
+- `unusedField` — `Protected readonly field "{{name}}" is not used in class or template.` autofix 는 필드 선언과 앞 들여쓰기·뒤 `;`·개행을 함께 제거.
+
+```typescript
+@Component({ template: `<div>{{title}}</div>` })
+class C { protected readonly title = "x"; protected readonly unused = 1; } // unused 제거
+```
 
 ## ng-template-no-strict-null-check
 
-`type: problem`, autofix 없음(인라인 템플릿 offset 매핑 문제로 미제공). Angular 템플릿 바인딩에서 `=== null`/`undefined`, `!== null`/`undefined` 금지, `== null`/`!= null` 강제.
+Angular HTML 템플릿에서 엄격 비교(`=== null`, `!== null`, `=== undefined`, `!== undefined`)를 금지하고 `== null`/`!= null` 로 통일하도록 강제. `type: "problem"`, autofix 없음(인라인 템플릿 offset 매핑 문제로 미제공), 옵션 없음. HTML 파일 대상.
+
+검사 대상: 템플릿 표현식의 `Binary` 노드 중 연산자가 `===`/`!==` 이고 양변 중 하나가 nil 리터럴(value 가 null/undefined)인 경우.
 
-- 감지: `===`/`!==` 이항 연산의 한쪽 피연산자가 `null`/`undefined` 리터럴(value 가 nil)인 경우.
-- `noStrictNullCheck` — `{{actual}}`(원본 표현식)·`{{replacement}}`(권장 표현식, `x == null`/`x != null`) 치환.
+메시지:
+- `noStrictNullCheck` — `{{actual}}`(예: `x === null`) 사용 금지, `{{replacement}}`(예: `x == null`) 사용 안내. `===`→`==`, `!==`→`!=` 로 변환한 권장 표현을 제시.
+
+```html
+@if (user !== null) {}  <!-- user != null 사용하라고 보고 -->
+```
 
 ## ng-template-no-todo-comments
 
-`type: problem`, autofix 없음, recommended 에서 `warn`. HTML 템플릿의 `<!-- TODO: ... -->` 주석을 감지. AST visitor 가 아니라 raw 텍스트 정규식으로 처리(visitor 는 빈 객체 반환).
+Angular HTML 템플릿 내 `<!-- TODO: ... -->` 주석을 경고. `type: "problem"`, autofix 없음, 옵션 없음. recommended 에서 `warn`. HTML 파일 대상.
 
-- 감지: HTML 주석(`<!-- ... -->`) 내부에 `TODO:` 가 포함된 경우. 메시지에는 `TODO:` 이후를 trim 한 본문을 그대로 출력.
-- `noTodo` — `{{content}}` 치환(주석에 적힌 TODO 내용).
+동작: raw 텍스트를 `<!--...-->` 정규식으로 훑어 주석 내용에 `TODO:` 가 있으면 보고(AST 방문자 없이 빈 객체 반환). 메시지 본문은 `TODO:` 뒤 trim 한 내용.
+
+메시지:
+- `noTodo` — 본문은 `{{content}}`(TODO 뒤 텍스트) 그대로 출력.
+
+```html
+<!-- TODO: 페이징 추가 -->  <!-- "페이징 추가" 경고 -->
+```
 
 ## ng-template-sd-require-binding-attrs
 
-`type: problem`, autofix 있음, 옵션 있음. `sd-` 접두사 컴포넌트에서 허용 목록 밖 plain attribute 사용을 금지하고 Angular property binding(`[attr]="..."`)을 강제.
+`sd-*` 접두사 커스텀 컴포넌트에서 허용목록 밖 plain attribute 사용을 금지하고 Angular property binding(`[attr]="..."`)을 강제. `type: "problem"`, autofix 있음. HTML 파일 대상. **유일하게 옵션 있는 규칙**.
+
+옵션(`RuleOptions`, 모두 선택):
+- `selectorPrefixes: string[]` — 검사 대상 요소 태그 접두사. 미지정 시 `["sd-"]`. 태그명을 소문자로 비교. 다른 디자인 시스템 접두사를 검사하려면 지정.
+- `allowAttributes: string[]` — plain attribute 로 허용할 정확한 이름 목록. 미지정 시 `["id","class","style","title","tabindex","role"]`. 소문자 비교. 추가로 허용할 표준 속성을 늘릴 때.
+- `allowAttributePrefixes: string[]` — plain attribute 로 허용할 접두사 목록. 미지정 시 `["aria-","data-","sd-"]`. 소문자 비교. 접두사 기반(aria/data 등) 속성군을 통째 허용할 때.
+
+동작: 대상 태그(접두사 매칭) 요소의 attribute 중 `allowAttributes`(정확 일치)·`allowAttributePrefixes`(접두사 일치) 어디에도 안 드는 것을 보고.
 
-- 옵션(객체 1개, 모든 키 선택):
-  - `selectorPrefixes: string[]` — 검사 대상 엘리먼트 태그 접두사. 기본 `["sd-"]`. 이 접두사로 시작하는 태그만 검사. 다른 디자인 시스템 접두사를 쓰면 그 값으로 교체.
-  - `allowAttributes: string[]` — plain 으로 허용할 attribute 이름. 기본 `["id","class","style","title","tabindex","role"]`. 대소문자 무시. 표준 전역 속성을 추가 허용할 때 확장.
-  - `allowAttributePrefixes: string[]` — plain 으로 허용할 attribute 접두사. 기본 `["aria-","data-","sd-"]`. 접근성·데이터 속성군을 통째로 허용.
-- autofix: 값 없는 attr → `[attr]="true"`, 값 있는 attr → `[attr]="'<escaped>'"`(`\`·`'` 이스케이프). 빈 span 이면 fix 생략.
-- `requireBindingForAttribute` — `{{attrName}}`·`{{elementName}}` 치환.
+메시지:
+- `requireBindingForAttribute` — `"{{attrName}}"` 은 `"{{elementName}}"` 의 plain attribute 로 불가, property binding 사용 안내. autofix 는 값이 빈 문자열이면 `[attr]="true"`, 값이 있으면 `\` 와 `'` 를 이스케이프해 `[attr]="'값'"` 로 치환(span 의 start≥end 면 수정 안 함).
 
-```js
-{ "@simplysm/ng-template-sd-require-binding-attrs": ["error", { allowAttributes: ["id", "for"] }] }
+```html
+<sd-button myattr="hello"></sd-button>   <!-- → <sd-button [myattr]="'hello'"></sd-button> -->
+<sd-button disabled></sd-button>          <!-- → <sd-button [disabled]="true"></sd-button> -->
 ```

package/claude/references/sd-simplysm14/apis/orm-common/README.md

@@ -1,67 +1,11 @@
 # @simplysm/orm-common
 
-Dialect 독립 ORM 코어. 테이블/뷰/프로시저를 빌더로 정의하고, `DbContext` 클래스에 등록한 뒤, 체이닝 `Queryable` 로 타입 안전한 SELECT/CUD 쿼리를 JSON AST(`QueryDef`/`Expr`)로 조립한다. 실제 SQL 변환·DB 연결은 dialect QueryBuilder(이 패키지) + `@simplysm/orm-node` 등 executor 가 담당.
+Dialect 독립적 ORM 코어. `DbContext` 를 상속해 테이블/뷰/프로시저를 등록하고, fluent `Queryable` 체이닝 + JSON AST `expr` 로 쿼리를 구성하면 dialect별 QueryBuilder 가 MySQL/MSSQL/PostgreSQL SQL 로 변환한다. 실제 DB 연결·실행은 `DbContextExecutor` 구현체(서버/클라이언트)가 담당하므로 이 패키지 자체는 SQL 문자열·QueryDef AST 까지만 생성한다.
 
 ## 사용 트리거 인덱스
 
-- **스키마 정의 (Table/View/Procedure/Column/Index/Relation 빌더)** — DB 객체를 fluent 빌더로 선언하고 column·PK·index·FK 관계를 잡을 때. 자세히: [schema.md](./schema.md)
-- **DbContext (연결·트랜잭션·DDL·마이그레이션·초기화)** — 빌더들을 한 컨텍스트에 등록하고 `connect`/`transaction` 으로 실행, DDL·migration·`initialize` 를 돌릴 때. 자세히: [db-context.md](./db-context.md)
-- **Queryable (SELECT/JOIN/INSERT/UPDATE/DELETE/UPSERT 체이닝)** — `db.user()` 로 받은 쿼리 빌더에 where/orderBy/join/include/group/recursive/union 을 걸고 execute/single/count/insert/update/delete/upsert 를 호출할 때. 자세히: [queryable.md](./queryable.md)
-- **expr (SQL 표현식 빌더)** — where/select/orderBy 콜백 안에서 비교·문자열·숫자·날짜·집계·조건·window·서브쿼리 표현식을 만들 때. 자세히: [expr.md](./expr.md)
-- **QueryDef / Expr / Column 타입** — executor·QueryBuilder 를 직접 구현하거나 AST·결과 메타를 다룰 때 참조하는 타입군. 자세히: [types.md](./types.md)
-- **QueryBuilder (dialect SQL 렌더러)** — QueryDef 를 mysql/mssql/postgresql SQL 로 변환하는 클래스. executor 구현체가 사용. 자세히: [query-builder.md](./query-builder.md)
-- **결과 파싱 유틸 / 검색 파서 / 프로시저 실행 / 에러** — 아래 인라인 섹션 참조.
-
-## Executable / executable (프로시저 실행)
-
-저장 프로시저를 `DbContext.executable(Procedure)` 로 등록하면 `() => Executable` 팩토리가 반환된다. `Executable` 은 프로시저 실행 래퍼.
-
-- `executable(db: DbContextBase, builder: ProcedureBuilder): () => Executable` — DbContext 내부에서 프로시저 getter 를 만드는 팩토리. 보통 `DbContext.executable()` 보호 메서드가 대신 호출.
-- `Executable.execute(params): Promise<TReturns[][]>` — 프로시저 실행. `params` 는 `ProcedureBuilder.params()` 로 정의한 키별 값(리터럴 또는 ExprUnit). 결과는 결과셋 배열의 배열.
-- `Executable.getExecProcQueryDef(params?)` — 실행용 `ExecProcQueryDef` 생성. 파라미터 미정의 프로시저에 값 전달 시 throw.
-
-```typescript
-const result = await db.getUserById().execute({ userId: 1 });
-```
-
-## 결과 파싱 유틸
-
-executor 가 DB raw 결과를 TS 객체로 환원할 때 쓰는 유틸. 일반 사용자는 직접 호출하지 않음.
-
-- `parseQueryResult<T>(rawResults, meta: ResultMeta): Promise<T[] | undefined>` — flat raw 행 배열을 `meta.columns`(키→타입) 로 타입 변환하고 `meta.joins`(키→`{isSingle}`) 로 중첩 그룹핑. 입력이 비었거나 파싱 후 전부 빈 객체면 undefined. async 전용(100행마다 이벤트 루프 양보). `isSingle:true` 관계에 서로 다른 다건이 매칭되면 throw.
-- `pickResultSets<T>(rawResults: T[][], buildResult): T[]` — 다중 결과셋에서 필요분 추출. `resultSetIndex` 없으면 첫 셋, `resultSetStride` 없으면 해당 인덱스 셋, 있으면 인덱스부터 stride 간격으로 concat(MySQL 배치 INSERT 의 SELECT 결과만 모을 때).
-
-## 검색 파서
-
-`Queryable.search()` 내부에서 쓰이며, 검색 문법 문자열을 SQL LIKE 패턴으로 변환.
-
-- `parseSearchQuery(searchText: string): ParsedSearchQuery` — 검색 문자열 파싱. 반환 `{ or, must, not }` 각각 LIKE 패턴 배열.
-  - `or: string[]` — 공백 구분 일반 토큰(OR, 하나 이상 일치). 와일드카드 없는 토큰은 `%토큰%`(부분 일치).
-  - `must: string[]` — `+토큰` 또는 `"정확한 구문"`(AND, 필수 포함).
-  - `not: string[]` — `-토큰`(NOT, 제외).
-  - 문법: `term1 term2`(OR), `+term`(필수), `-term`(제외), `"구문"`(정확·필수), `*`(와일드카드→`%`). 이스케이프 `\\ \* \% \" \+ \-`. 닫히지 않은 따옴표는 일반 텍스트.
-- `interface ParsedSearchQuery` — 위 `or`/`must`/`not` 세 LIKE 패턴 배열을 담는 타입.
-
-## 에러 (DbTransactionError / DbErrorCode)
-
-DBMS 네이티브 트랜잭션 에러를 표준 코드로 래핑. `connect`/`transaction` 의 롤백 경로에서 발생.
-
-- `class DbTransactionError extends Error` — 표준화된 트랜잭션 에러.
-  - `code: DbErrorCode` — 표준 에러 코드.
-  - `message: string` — 에러 메시지(생성자 2번째 인자).
-  - `originalError?: unknown` — 원본 DBMS 에러(디버깅용).
-  - `name` — 항상 `"DbTransactionError"`.
-- `enum DbErrorCode` — 표준 트랜잭션 에러 코드.
-  - `NO_ACTIVE_TRANSACTION` — 활성 트랜잭션 없는데 ROLLBACK 시도. 롤백 중 이 코드면 `connect`/`transaction` 이 무시(원 에러 보존).
-  - `TRANSACTION_ALREADY_STARTED` — 이미 트랜잭션 시작됨.
-  - `DEADLOCK` — 데드락 발생.
-  - `LOCK_TIMEOUT` — 잠금 타임아웃.
-
-```typescript
-try {
-  await db.rollbackTransaction();
-} catch (err) {
-  if (err instanceof DbTransactionError && err.code === DbErrorCode.NO_ACTIVE_TRANSACTION) return;
-  throw err;
-}
-```
+- **DbContext / 연결 / 트랜잭션 / DDL / 마이그레이션** — DB 컨텍스트 클래스를 정의하거나, `connect`/`transaction` 으로 쿼리를 감싸거나, 스키마를 생성·변경하거나, `initialize`/`migrations` 로 마이그레이션을 돌릴 때. `DbTransactionError`·`Migration`·`IsolationLevel`·`DbContextExecutor` 포함. 자세히: [db-context.md](./db-context.md)
+- **스키마 정의 (Table / View / Procedure / column / index / relation)** — `Table(...)`/`View(...)`/`Procedure(...)` 빌더로 테이블·뷰·프로시저 스키마와 column·PK·index·FK 관계를 선언하고 타입을 추론할 때. 자세히: [schema.md](./schema.md)
+- **Queryable 체이닝 / CRUD 실행 / 검색** — `db.X()` 로 얻은 `Queryable` 을 `select`/`where`/`join`/`include`/`groupBy`/`orderBy` 로 조립하고 `execute`/`single`/`count`/`insert`/`update`/`delete`/`upsert` 로 실행할 때. `Queryable.union`·`search`·`Executable`·`parseSearchQuery` 포함. 자세히: [queryable.md](./queryable.md)
+- **expr 표현식 빌더** — `where`/`select`/`orderBy`/`having` 콜백 안에서 비교·논리·문자열·숫자·날짜·집계·window·조건·서브쿼리 표현식을 만들 때. `ExprUnit`/`WhereExprUnit`/`ExprInput` 포함. 자세히: [expr.md](./expr.md)
+- **하위 타입 / QueryDef AST / QueryBuilder / 결과 파싱** — Executor·QueryBuilder 를 직접 구현하거나, `QueryDef` AST·`Expr` AST·column 타입을 다루거나, 원시 결과를 `parseQueryResult`/`pickResultSets` 로 변환할 때. 자세히: [types.md](./types.md)