feat: schema usr와 reach·impact language-traversal 순회 문서

[ictechgy]

요약

API 영향 추적 Phase 7c(Rust). isthmus trace가 Rust 백엔드의 핸들러 도달과 relation-use를 잇도록 두 가지를 더합니다.

1. schema 사실의 symbol.usr: 사실을 감싸는 그래프 아이템 ID를 싣습니다. impact·graph --level symbol과 같은 ID입니다.
2. language-traversal v1 출력: reach(dependencies)와 impact --format language-traversal(dependents)을 추가합니다.

ID 체계와 usr 귀속

• ID 형식
  • 일반 아이템: crate::mod::f, crate::mod::Type
  • inherent 메서드: crate::mod::Type::method
  • trait impl 메서드: crate::mod::Type::<Trait>::method
  • trait 기본 메서드: crate::mod::Trait::method
• 찾는 방법: 같은 syn 수확으로 정점별 소스 범위(harvest::OwnerSpan)를 받습니다. 사실의 바이트 오프셋을 감싸는 가장 안쪽 정점을 고르고, 그 ID가 그래프 정점 집합에 있을 때만 싣습니다.
• 귀속 대상
  • fn, impl 메서드, trait 기본 메서드, const/static 초기화식: 그 정점
  • 구조체 어트리뷰트·필드 컬럼: 구조체
  • 메서드 밖의 연관 상수: impl의 self 타입
  • fn 안의 fn: 바깥 fn
• usr가 없는 경우: 최상위 table!, orphan 파일, 수확 실패. 이런 사실은 missing-relation-usrs:로 셉니다.

순회 문서

• 다중 root 단일 패스 (src/traversal.rs, pythograph 알고리즘 포팅)
  • 한 정점에 싣는 root는 최대 64개이고, 넘으면 rootsTruncated입니다. root가 65개를 넘으면 전파를 멈춥니다.
  • via는 UTF-16 순서로 고릅니다.
  • root별 BFS 오라클과 무작위 그래프 300개로 대조했고, 80개 root가 한 hub로 모이는 경우도 확인했습니다.
• 근거 등급: tentative 간선은 candidate로 봅니다. 모든 도달 정점에 root별 하한 evidence를 싣습니다. dispatch·unresolvedCalls는 싣지 않습니다.
• 입력과 메타데이터
  • --roots-from은 JSON 배열 또는 bridge-facts 문서를 받습니다.
  • 깊이는 --max-depth(1–128)로 정하고 --depth도 받습니다. 도달 수 상한은 --max-reached입니다.
  • revision은 --revision, 없으면 깨끗한 작업 트리의 HEAD입니다.
  • graphRevision은 SHA-256입니다. 저장소 안에 구현했고 NIST 벡터로 검증했습니다.
• 종료 코드
  • root-not-found: 문서를 쓰고 64로 끝납니다.
  • 사용법 오류: 표준 출력을 비우고 64로 끝납니다.

e2e (scratch, 합성 axum·sqlx·sea_orm 스텁)

isthmus f9dcd1d와 schemagraph 703a21f로 돌렸습니다.

• isthmus check --pairs: 종료 코드 0, 5 matches.
• trace, relation 선택: relation → relation-use(usr) → 역방향 순회까지 이어집니다. rust route-decl이 없어서 non-http-entry에서 멈춥니다. 문서는 isthmus 파서를 통과했습니다.
• trace, route 선택: 원본 isthmus는 rust route-decl을 거부합니다. 그래서 scratch에서 isthmus를 고치고 손으로 만든 route-decl로 확인했습니다.
  • /api/orders/{} → OrderStore::find → main.orders·main.order_items → DB 의존자
  • syn 모드는 메서드 이름 팬아웃이라 이 경로도 candidate입니다.

남은 것

• Rust route-decl 생산자가 필요하고, isthmus의 계약 개정이 필요합니다.
• 기존 수확 결함(이번 범위 밖): 지역 변수 이름이 크레이트 루트 모듈 이름과 같으면 모듈 정점을 가리키는 references 간선이 생깁니다. 그래서 순회가 그 모듈이 import한 아이템 전부에 닿습니다. 자세한 내용은 HANDOFF에 적었습니다.
• cycles --level type이 10개에서 13개로 늘었습니다. 같은 투영 산물이고 게이트 대상이 아닙니다.

검증

• cargo fmt --check 통과
• cargo clippy --all-targets -D warnings 통과 (semantic feature 포함)
• cargo test 157개 통과 (semantic 포함)
• scripts/coverage.sh 통과 (93.64%, 게이트 90)
• scripts/verify-cli-contract.sh OK
• 자기 분석: rules --strict 0, cycles --level symbol --strict 0
• GLM 리뷰: 실제 결함 2건을 수정했습니다.
  • --generated-at의 범위 밖 오프셋(+99:99)을 받아들이던 문제
  • impact --format=language-traversal 표기의 파싱 실패가 2로 끝나던 문제
• GLM 지적 중 재현이나 계약으로 반박한 것
  • 경로 정규화 불일치: 심링크 경로와 상대 경로에서 6/6 usr가 붙는 것을 확인했습니다.
  • root-not-found를 truncationReasons에 넣는 것: 계약이 요구하는 동작입니다.
  • showUntrackedFiles 설정 문제: --untracked-files=normal을 명시해서 설정을 덮어씁니다.
  • 정점 ID 조회가 이차 시간이라는 지적: 실제로는 BTreeSet 조회입니다.

🤖 Generated with Claude Code