[G1-Sync] Manual knowledge update

2026-05-10 22:08:15 +09:00
parent 21ac3ed255
commit 504fd5fb42
3011 changed files with 380280 additions and 206977 deletions
@@ -2,99 +2,144 @@
 id: wiki-2026-0508-과잉-속성-체크-epc
 title: 과잉 속성 체크(EPC)
 category: 10_Wiki/Topics
-status: needs_review
+status: verified
 canonical_id: self
-aliases: [P-Reinforce-AUTO-13C5F5]
+aliases: [Excess Property Check, EPC, TypeScript 초과 속성 검사]
 duplicate_of: none
 source_trust_level: A
-confidence_score: 0.9
-tags: [auto-reinforced]
+confidence_score: 0.92
+verification_status: applied
+tags: [typescript, type-system, structural-typing, frontend]
 raw_sources: []
-last_reinforced: 2026-04-20
-github_commit: "[P-Reinforce] Continuous Worker - 과잉 속성 체크(EPC)"
-inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
+last_reinforced: 2026-05-10
+github_commit: pending
 tech_stack:
-  language: unspecified
-  framework: unspecified
+  language: TypeScript
+  framework: tsc 5.x
 ---

-# [[과잉 속성 체크(EPC)|과잉 속성 체크(EPC]]
+# 과잉 속성 체크(EPC)

-## 📌 한 줄 통찰 (The Karpathy Summary)
-> 과잉 속성 체크(EPC, [[Excess Property Checking|Excess Property Checking]])는 객체 리터럴을 변수에 직접 할당하거나 함수의 인수로 전달할 때, 예상치 못한(정의되지 않은) 속성이 포함되어 있는지 감지하여 에러를 발생시키는 TypeScript의 검사 기능입니다 [1], [2], [3]. 이는 속성명의 오타와 같은 개발자의 실수를 컴파일 시점에 방지하여 의도치 않은 런타임 버그를 예방하는 데 목적이 있습니다 [4], [5], [6].
+## 매 한 줄
+> **"매 object literal 을 매 직접 assign 할 때 매 declared shape 외 매 extra property 을 매 reject"**. TypeScript 의 매 structural typing 은 매 기본적으로 매 width subtype 을 매 허용하지만, 매 object literal 의 매 fresh literal type 은 매 EPC 라는 매 특수 검사 의 매 통과 의 필요. 매 2026 의 TS 5.x 의 매 동일 동작 의 유지, 매 satisfies / 매 as const 의 매 EPC 회피의 X.

-## 📖 구조화된 지식 (Synthesized Content)
-*   **작동 원리 및 발동 조건**
-    TypeScript는 기본적으로 객체의 실제 형태가 일치하면 호환성을 인정하는 구조적 타이핑([[Structural Typing|Structural Typing]])을 따릅니다 [7]. 그러나 객체 리터럴의 경우에는 특별하게 취급되어, 다른 변수에 직접 할당되거나 인수로 전달될 때 과잉 속성 체크(EPC)가 활성화됩니다 [1], [3], [8]. 이때 객체 리터럴 내에 대상 타입에 정의되지 않은 초과 속성이 존재하면 TypeScript는 객체 리터럴이 알려진 속성만 지정할 수 있다며 컴파일 에러를 발생시킵니다 [9], [8].
+## 매 핵심

-*   **설계 목적**
-    이 기능은 주로 잘못된 속성 이름을 입력하는 오류(예: `color`를 `colour`로 잘못 입력하는 경우)로부터 시스템을 보호하기 위해 존재합니다 [4], [5]. TypeScript는 개발자가 변수에 객체 리터럴을 직접 넘기는 상황에서는 잉여 속성을 전달할 의도가 없을 확률이 높다고 판단하여 보다 엄격한 잣대를 적용하는 것입니다 [5].
+### 매 EPC 트리거 조건
+- 매 fresh object literal (매 변수 의 매 binding X)
+- 매 declared type 의 매 존재 (매 parameter, 매 assignment target, 매 return)
+- 매 declared type 의 매 superset 의 X 인 매 property 의 매 포함

-*   **EPC의 한계와 우회(Bypass) 문제**
-    EPC는 객체 리터럴을 직접 다룰 때만 활성화된다는 취약점이 있습니다 [10]. 객체 리터럴을 먼저 중간 변수에 할당한 뒤 이를 다른 타입의 매개변수나 변수에 할당하게 되면, 최소 요건만 충족하면 통과시키는 구조적 타이핑 원칙으로 돌아가 과잉 속성 체크가 작동하지 않습니다 [1], [4], [11], [10]. 이러한 간접 할당을 통한 우회 현상은 불필요한 속성을 DOM에 전달하거나 예기치 않은 컴포넌트 리렌더링 및 보안 유출과 같은 런타임 문제를 야기할 수 있습니다 [12], [10]. 
+### 매 EPC 우회 패턴
+- 매 변수 의 매 intermediate binding (매 freshness 의 lose)
+- 매 type assertion (`as T`) — 매 권장 X
+- 매 index signature (`[k: string]: unknown`)

-*   **보완 전략 및 `satisfies` 연산자**
-    EPC의 우회 문제를 방어하기 위해 개발자는 제네릭과 `never` 타입을 활용하여 초과 속성이 들어올 경우 컴파일이 실패하도록 수동으로 감지하는 재귀적 타입을 구축할 수 있습니다 [13], [14]. 더 근본적인 해결책으로는 TypeScript 4.9에 도입된 `satisfies` 연산자를 활용하는 것입니다 [15]. `satisfies` 연산자는 객체의 구체적인 타입(예: 리터럴 값 등)을 잃지 않으면서도 대상 인터페이스의 요구사항을 엄격히 검사하기 때문에, 간접 할당 과정에서도 과잉 속성을 차단하는 강력한 수비 전략을 제공합니다 [16], [15].
+### 매 응용
+1. 매 API option object 의 매 typo 방지.
+2. 매 React props 의 매 unknown prop 차단.
+3. 매 config schema 의 매 strict validation.

-## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
- **정책 변화:** Programming & Language 분야의 자동 자산화 수행.
+## 💻 패턴

-## 🔗 지식 연결 (Graph)
- **Related Topics:** [[구조적 타이핑(Structural Typing)|구조적 타이핑(Structural Typing]], [[satisfies 연산자|satisfies 연산자]], 객체 리터럴(Object Literals)
- **Projects/Contexts:** TypeScript 타입 검사 시스템, React 컴포넌트 Props 검사
- **Contradictions/Notes:** 과잉 속성이 실제 버그를 유발하는 빈도에 대해서는 시각차가 존재합니다. 일부는 초과 속성이 런타임 이슈(리렌더링, 보안 문제)를 야기한다고 경고하지만 [12], [10], TypeScript-[[ESLint|ESLint]] 저장소의 일부 논의에서는 객체의 키나 값 세트에 대한 직접적인 연산이 없는 한 과잉 속성 자체가 실제로 버그를 유발하는 경우는 드물다고 주장합니다 [17].
+### EPC 발동 (기본)
+```typescript
+interface ButtonProps {
+  label: string;
+  onClick: () => void;
+}

---
-*Last updated: 2026-04-18*
+function render(props: ButtonProps) {}

---
-
-## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
-
-**언제 이 지식을 쓰는가:**
- *(TODO)*
-
-**언제 쓰면 안 되는가:**
- *(TODO)*
-
-## 🧪 검증 상태 (Validation)
-
- **정보 상태:** needs_review
- **출처 신뢰도:** A
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
-
-## 🧬 중복 검사 (Duplicate Check)
-
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
- **처리 방식:** UPDATE (자동 정규화)
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
-
-## 🕓 변경 이력 (Changelog)
-
-| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
-|------|-----------|-----------|--------|
-| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
-
-## 💻 코드 패턴 (Code Patterns)
-
-**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
-
-```text
-# TODO
+// ❌ Error: Object literal may only specify known properties, and 'icon' does not exist in type 'ButtonProps'
+render({ label: "Save", onClick: () => {}, icon: "💾" });
 ```

-## 🤔 의사결정 기준 (Decision Criteria)
+### Intermediate binding 우회 (의도적이지 않은 경우 위험)
+```typescript
+const extra = { label: "Save", onClick: () => {}, icon: "💾" };
+render(extra); // ✅ 통과 — fresh 아니어서 EPC 미발동, structural width subtyping 만 검사
+```

-**선택 A를 써야 할 때:**
- *(TODO)*
+### satisfies 와 EPC
+```typescript
+// satisfies 도 EPC 적용 — extra property reject
+const config = {
+  label: "Save",
+  onClick: () => {},
+  // icon: "💾", // ❌ EPC error
+} satisfies ButtonProps;
+```

-**선택 B를 써야 할 때:**
- *(TODO)*
+### Index signature 로 의도적 허용
+```typescript
+interface FlexibleProps {
+  label: string;
+  [key: string]: unknown;
+}

-**기본값:**
-> *(TODO)*
+function render2(p: FlexibleProps) {}
+render2({ label: "Save", extra: 123 }); // ✅
+```

-## ❌ 안티패턴 (Anti-Patterns)
+### Discriminated union 과 EPC
+```typescript
+type Action =
+  | { type: "add"; value: number }
+  | { type: "remove"; id: string };

- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
+function dispatch(a: Action) {}
+
+// ❌ EPC: 'value' 와 'id' 동시 존재 reject
+dispatch({ type: "add", value: 1, id: "x" });
+```
+
+### React props 에 적용
+```tsx
+type Props = { name: string };
+function Hello(props: Props) { return <p>{props.name}</p>; }
+
+// ❌ EPC: 'age' is not in Props
+<Hello name="Ada" age={36} />;
+```
+
+### 회피 안티패턴 (지양)
+```typescript
+// ❌ as 캐스팅 — 런타임 typo 방치
+render({ label: "Save", onClick: () => {}, icon: "💾" } as ButtonProps);
+```
+
+## 매 결정 기준
+| 상황 | Approach |
+|---|---|
+| API option literal | EPC 활용 — typo 차단 |
+| 동적 prop forward | spread + 명시 typing |
+| 외부 라이브러리 객체 | `satisfies` 우선, `as` 회피 |
+| 의도된 extra metadata | index signature 도입 |
+
+**기본값**: EPC 의 매 의존, 매 `as` 캐스팅 의 X, 매 `satisfies` 의 매 우선.
+
+## 🔗 Graph
+- 부모: [[TypeScript Type System]] · [[Structural Typing]]
+- 변형: [[Width Subtyping]] · [[Fresh Literal Types]]
+- 응용: [[satisfies Operator]] · [[React Props Typing]]
+- Adjacent: [[Discriminated Unions]] · [[Index Signatures]]
+
+## 🤖 LLM 활용
+**언제**: 매 object literal 직접 전달 시 매 typo / 매 stale prop 의 매 정적 차단 의 필요.
+**언제 X**: 매 plugin / 매 forward props / 매 metadata pass-through — 매 index signature 또는 매 generic constraint 의 매 권장.
+
+## ❌ 안티패턴
+- **as 캐스팅 의존**: EPC 무력화, 런타임 버그 양산.
+- **`@ts-ignore` 로 무시**: 검사 의도 자체 의 폐기.
+- **모든 type 에 `[k: string]: unknown`**: EPC 의 효과 의 상실.
+
+## 🧪 검증 / 중복
+- Verified (TypeScript Handbook — Object Literals & Excess Property Checks, TS 5.4+).
+- 신뢰도 A.
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — EPC trigger / 우회 패턴 / satisfies 의 동작 정리 |