Feat: Type graph 기반 서브시스템 결과 보정을 위한 Refiner 및 Semantic Signal 확장

[jurutang]

배경

현재 cluster 도메인은 graphstore의 SymbolEntity + Edge로 구성된 Type graph만을 기반으로 Leiden 알고리즘을 수행해 서브시스템을 도출한다.

하지만 commons-cli 분석 결과, 전체 56개 타입 중 misc에 41개가 남는 등 Type graph만으로는 사람이 보는 기능적 서브시스템을 충분히 복원하기 어렵다는 한계가 확인되었다.

정리하면 현재 구조는 다음과 같다.

• Type graph clustering = 구조적 결합 기반 1차 서브시스템 추정
• Type graph clustering ≠ 기능적 서브시스템의 정답 복원

따라서 Type graph와 graphstore DB는 유지하되, cluster 도메인 내부에서만 후처리 규칙과 의미 기반 synthetic edge를 추가해 서브시스템 품질을 개선한다.

---

목표

• graphstore DB, Entity, 저장 로직은 변경하지 않는다.
• EdgeWeightPolicy는 변경하지 않는다.
• 보조 의미 신호는 ProjectedGraph 메모리 단계에서 synthetic edge로만 주입한다.
• 결정적 규칙은 SubsystemRefiner에서 후처리한다.
• 통계적/연속적 신호는 SemanticSignalProvider로 분리한다.
• 각 단계는 독립 PR로 진행하고, artifact에 baseline 메타를 남긴다.
• provider별 ON/OFF 토글을 제공해 ablation 실험이 가능하도록 한다.

---

설계 원칙

변경하지 않는 것

• graphstore 도메인
• DB schema / migration
• EdgeWeightPolicy
• ResolutionProbeService
• LeidenCommunityService
• SubsystemAssembler의 minClusterSize 정책
• RankingService

신규 구조

ClusterBuildService
    ↓
GraphProjectionService
    ├── 기존 graphstore Edge → ProjectedEdge
    └── SemanticSignalAugmenter
          ├── PackageSignalProvider
          ├── NameSimilaritySignalProvider
          ├── DocCommentSignalProvider
          └── PublicApiFlowSignalProvider
    ↓
ProjectedGraph
    ↓
ResolutionProbeService → LeidenCommunityService
    ↓
SubsystemAssembler
    ↓
SubsystemRefiner
          ├── OwnerAbsorptionRule
          └── ExceptionLineageRule
    ↓
ClusterRefineMetadata
    ↓
RankingService
    ↓
ClusterArtifactPublisher

---

구현 단계

1단계: SubsystemRefiner 추가

Leiden 결과 이후 결정적 구조 규칙을 기반으로 subsystem을 보정한다.

• OwnerAbsorptionRule

  • inner class, Builder, 중첩 enum 등을 owner subsystem으로 이동
  • owner chain 무한 순환 방지를 위해 max-depth 적용

• ExceptionLineageRule

  • graphstore raw Edge 중 edgeType=EXTENDS인 데이터만 사용
  • ParseException 계열 등 같은 exception lineage를 하나의 subsystem으로 정리
  • ProjectedEdge는 EdgeType 정보가 없으므로 사용하지 않음

2단계: SemanticSignalProvider 구조 추가

ProjectedGraph 생성 단계에서 보조 의미 신호를 synthetic edge로 주입할 수 있는 구조를 추가한다.

• SemanticSignalProvider 인터페이스 추가
• SemanticSignalAugmenter 추가
• provider별 ON/OFF 토글 지원

3단계: PackageSignalProvider 추가

같은 packageName에 속한 타입 사이에 약한 synthetic edge를 추가한다.

• baseWeight 기본값: 0.15
• 큰 패키지는 weight decay 또는 star topology 적용
• 너무 큰 패키지는 signal 차단

4단계: NameSimilaritySignalProvider 추가

simpleName의 CamelCase 토큰 유사도를 기반으로 synthetic edge를 추가한다.

• Jaccard 유사도 기반
• Builder, Exception, Abstract, Default 등 범용 토큰은 stopword 처리
• Option, Parser, Help 같은 도메인 핵심 단어는 stopword에 포함하지 않음

5단계: DocCommentSignalProvider / PublicApiFlowSignalProvider 검토

• docComment 기반 TF-IDF 유사도
• PublicApiEntry 기반 API flow set
• 두 기능은 앞 단계 효과 확인 후 별도 PR로 진행

---

작업 목록

• ClusterSignalProperties 추가
• SubsystemRefinementRule 인터페이스 추가
• RefinementResult 추가
• OwnerAbsorptionRule 추가
• ExceptionLineageRule 추가
• SubsystemRefinerService 추가
• ClusterBuildService에 Refiner 호출 추가
• SubsystemsJson.algorithm에 refiner 메타 추가
• SemanticSignalProvider 인터페이스 추가
• SemanticSignalAugmenter 추가
• PackageSignalProvider 추가
• GraphProjectionService에서 Augmenter 호출 위치 추가
• signals/refiner ON/OFF 설정 추가
• commons-cli 기준 baseline 결과 비교

---

검증 기준

• graphstore DB, Entity, Repository 변경이 없어야 한다.
• EdgeWeightPolicy는 변경하지 않는다.
• Refiner 적용 후 modularity 값은 변하지 않아야 한다.
  • Leiden 결과 자체가 아니라 후처리 label만 바꾸기 때문
• commons-cli 기준 misc 비율 변화를 기록한다.
• Builder / inner class가 owner subsystem으로 재배치되는지 확인한다.
• ParseException 계열이 하나의 exception subsystem으로 정리되는지 확인한다.
• synthetic edge 수가 과도하게 증가하지 않는지 확인한다.
• SubsystemsJson.algorithm에 다음 메타가 기록되어야 한다.

{
  "metrics": {
    "misc_node_count": 28,
    "total_node_count": 56,
    "misc_ratio": 0.50,
    "subsystem_count": 5,
    "avg_subsystem_size": 5.6,
    "stddev_subsystem_size": 2.3,
    "modularity": 0.42,
    "leiden_resolution": 1.0,
    "leiden_iterations": 10
  }
}

---

완료 조건

• cluster 도메인 내부 변경만으로 Refiner와 Semantic Signal 구조가 추가된다.
• graphstore DB와 EdgeWeightPolicy는 변경되지 않는다.
• 단계별 ON/OFF 설정이 가능하다.
• commons-cli 기준 기존 결과와 개선 후 결과를 비교할 수 있는 메타가 artifact에 남는다.
• 이후 Package / Name / Doc / API Flow signal을 독립 PR로 확장할 수 있는 구조가 마련된다.