IP-7079: [compose] 내부 유틸리티 함수의 flat/recursive 의도를 이름에 반영

[novdov]

목적

Evaluable 클래스와 evaluate 함수의 이름이 flat/recursive 차이를 드러내지 않아 혼동 가능성이 있으므로, evaluate/deep_evaluate 함수 쌍으로 통일하여 의도를 명확히 표현

변경 사항

• Evaluable 클래스를 deep_evaluate 함수로 전환
  • Operator 서브클래스에서 일반 함수로 변경하여 내부 유틸리티 성격을 명확히 표현
  • Evaluable(x).expression() 보일러플레이트를 deep_evaluate(x) 호출로 단순화
• 사용처 일괄 전환: base.py, stage.py, raw.py, array_expression.py, conditional.py의 모든 Evaluable 참조를 deep_evaluate로 변경
• rationale 문서 및 테스트 반영: 변경된 이름과 사용 패턴에 맞게 업데이트

Summary by CodeRabbit

릴리스 노트

• 리팩토링
  • 내부 평가 메커니즘을 최적화했습니다. 공개 API는 변경되지 않았으며, 시스템의 안정성과 성능이 향상되었습니다.

[linear]

IP-7079 [compose] 내부 유틸리티 함수의 flat/recursive 의도를 이름에 반영

배경

• evaluate(flat)와 Evaluable(recursive)은 operator 직렬화 시 중첩 Operator를 해결하는 내부 유틸리티
• 둘 다 "evaluate"라는 어근을 공유하지만, 핵심 차이인 flat vs recursive가 이름에 드러나지 않음
• Evaluable은 -able 접미사로 인해 프로토콜/인터페이스처럼 보이지만, 실제로는 재귀 평가를 수행하는 래퍼
• Operator 서브클래스일 필요 없는 내부 유틸리티가 도메인 연산자와 같은 형태를 가짐

목표

• evaluate와 deep_evaluate 함수 쌍으로 통일하여 이름에서 flat/recursive 차이가 바로 드러나게 함
• 불필요한 Evaluable(x).expression() 보일러플레이트 제거

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: a0e307a0-e24c-4465-b0df-5130357beae1

📥 Commits

Reviewing files that changed from the base of the PR and between 881b558 and 696d58d.

📒 Files selected for processing (7)

• compose/query/mongo/op/aggregation/array_expression.py
• compose/query/mongo/op/aggregation/conditional.py
• compose/query/mongo/op/base.py
• compose/query/mongo/op/raw.py
• compose/query/mongo/op/stage.py
• docs/rationale/20260212-evaluable-vs-evaluate.md
• tests/query/unit/test_evaluable_expression.py

---

Walkthrough

Evaluable 클래스를 새로운 deep_evaluate 함수로 대체하는 리팩토링입니다. 중첩된 구조를 재귀적으로 평가하는 내부 평가 헬퍼의 구현을 변경하며, 공개 API 서명은 변경하지 않습니다.

Changes

Cohort / File(s)	Summary
Base Module Refactoring compose/query/mongo/op/base.py	Evaluable 클래스를 제거하고 중첩된 Operator, 딕셔너리, 리스트를 재귀적으로 평가하는 새로운 deep_evaluate(value: Any) 함수를 추가합니다.
Aggregation Operators compose/query/mongo/op/aggregation/array_expression.py, compose/query/mongo/op/aggregation/conditional.py, compose/query/mongo/op/stage.py	Evaluable(...).expression() 호출을 deep_evaluate(...) 호출로 대체합니다. Map, Size, Filter, Reduce, SortArray, Cond, Spec, ReplaceRoot, Group 등의 평가 로직이 변경됩니다.
Raw Operator compose/query/mongo/op/raw.py	Evaluable 임포트를 제거하고 deep_evaluate 함수를 사용하도록 expression() 메서드를 업데이트합니다.
Documentation & Tests docs/rationale/20260212-evaluable-vs-evaluate.md, tests/query/unit/test_evaluable_expression.py	Evaluable에서 deep_evaluate로의 용어 및 사용 패턴을 업데이트합니다. 테스트는 직접 값 평가로 변경되며, 예상 결과가 완전히 해결된 딕셔너리 형식으로 확장됩니다.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 Evaluable은 물러나고,
deep_evaluate의 시대가 왔네!
중첩된 구조들이 깊게 평가되고,
코드는 더 명확하고 우아해진다.
버전 업그레이드, 우리의 마법! ✨

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}