ikieEngineeringGet started
All posts

온톨로지정적 분석CI개발 도구

코드로 그래프를 지어 "이걸 바꾸면 어디가 깨지나"에 답해요

ikie는 TypeScript·Swift 코드, DB, API 계약, 앱 정책에서 그래프를 자동으로 지어 "이걸 바꾸면 어디를 같이 봐야 하지?"에 답해요. 그래프가 맞히는지는 사람이 확인한 정답지로 PR마다 채점하고, 그래프로 찾은 원칙의 빈틈은 CI가 막아요.

English

일정의 반복 규칙 칸을 고친다고 해 봐요. 같이 봐야 할 곳은 어디일까요? 반복을 펼치는 계산은 당연하고, Google·iCloud·Outlook·iPhone 캘린더 어댑터마다 반복 칸을 읽고 쓰는 곳이 있어요. API 문서의 칸, iOS 앱의 시트, 시험도 있어요. 이 목록을 사람이 기억에 기대 만들면 하나씩 빠져요. 빠진 곳은 배포한 뒤에 버그로 돌아오고요.

글자로 찾기(grep)도 모자라요. SQL은 표 이름을 템플릿 문자열 안에 넣고, iOS 앱은 API를 주소가 아니라 생성된 함수 이름으로 부르고, 웹 폼은 API 주소를 action 속성에 문자열로 적어요. 그래서 ikie는 코드에서 그래프를 지어요. 우리는 이것을 온톨로지라고 불러요.

원천에서 자동으로 지어요

그래프에 사실을 손으로 적지 않아요. 손으로 쓰는 것은 노드와 연결의 종류(어휘)뿐이고, 모든 사실은 이미 있는 원천에서 읽어요.

원천읽는 법나오는 것
모델 선언model.ts를 읽어요칸, 외부 캘린더 대응, 동기화 칸 묶음
DB마이그레이션 파일을 빈 메모리 Postgres(PGlite)에 차례로 적용하고 정보 스키마를 읽어요표, 칸, 외래 키
API 계약OpenAPI 문서스키마, 칸, 라우트가 받고 돌려주는 것
앱 정책·화면 기능packages/policy 선언규칙, 시나리오, 기능마다 웹·iOS 파일
TypeScript컴파일러 API로 이름 단위까지가져오기, 이름 참조, 부르는 API, SQL 표 이름, 시험
Swifttree-sitter 문법 트리타입, 칸, 확장, 프로토콜 구현, 부르는 API

지금 그래프는 노드 약 26,600개, 연결 약 84,400개예요. 노드 종류는 22가지, 연결 종류는 28가지고요. 한 번 짓는 데 개발 환경에서 41초 걸렸어요. 지은 그래프는 커밋하지 않아요. 원천이 같으면 늘 같은 그래프가 나와야 해서, CI는 그래프를 두 번 지어 두 파일이 다르면 실패시켜요.

Swift는 받는 쪽 타입을 모르면 흔한 이름(id, title 같은)을 아무 데나 잇지 않고 "모름"으로 남겨요. 틀린 연결은 빠진 연결보다 나빠요. 영향 범위가 부풀면 사람이 목록을 믿지 않게 되니까요.

영향 범위는 거꾸로 걸어요

"이걸 바꾸면 무엇이 영향을 받나"는 그 노드에 기대는 쪽으로 연결을 거꾸로 걸어 가며 찾아요. 몇 걸음 떨어졌는지도 함께 적어 가까운 것부터 보여요.

impact(id: string): Map<string, number> {
  const seen = new Map<string, number>([[id, 0]]);
  const opened = new Set([id]);
  const queue = [id];
  while (queue.length) {
    const cur = queue.shift()!;
    for (const e of this.in.get(cur) ?? []) {
      if (!this.dep(e.type)) continue;
      if (!seen.has(e.from)) seen.set(e.from, seen.get(cur)! + 1);
      if (typeOnly(e) || opened.has(e.from)) continue;
      opened.add(e.from);
      queue.push(e.from);
    }
  }
  seen.delete(id); return seen;
}

타입으로만 쓰는 곳은 목록에 넣되 그 너머로는 걷지 않아요. 타입 하나를 가져다 쓴 파일마다 그 파일을 쓰는 모든 곳으로 퍼지면 목록이 쓸모없이 커지거든요.

처음의 질문에 그래프는 이렇게 답해요. npm run onto -- impact field:recurrence는 30개에 닿아요. 반복을 다루는 계산 11개(Google의 toGoogle·fromGoogle, Outlook, CalDAV writeUnits, iPhone 캘린더 어댑터를 포함해서), 코드 이름 12개(동기화 값의 반복 칸 셋 포함), 동기화 묶음 하나, 시험 6개예요.

고치기 전에 먼저 알려 줘요

그래프는 사람이 일부러 물어볼 때만 쓰이면 금방 잊혀요. 그래서 ikie를 만드는 Claude Code 세션에는 훅이 붙어 있어요. 파일을 고치려는 순간, 그 파일이 닿는 규칙·API·화면·DB 표, 돌려 볼 시험, 이 파일에 기대는 파일을 가까운 것부터 짧게 넣어 줘요. 한 세션에 파일마다 한 번, 한 번에 3KB까지예요. 일을 끝낼 때는 기준(base) 그래프와 견줘 새로 생긴 오류가 있으면 한 번 막아요.

매 PR, 무엇이 바뀌었는지 의미로 보여 줘요

텍스트 diff는 "몇 줄이 바뀌었다"를 보여요. 그래프 diff는 "무엇과 무엇의 관계가 바뀌었다"를 보여요. CI는 main 빌드가 남겨 둔 기준 그래프와 PR의 그래프를 견주고, 바뀐 관계를 중심 노드별로 묶어 영향 범위가 몇에서 몇으로 바뀌었는지 PR 댓글 하나로 달아요. 새로 생긴 검사 오류와 고쳐진 오류도 함께요. 자리만 옮긴 것은 빼서, 리뷰어는 구조가 바뀐 곳만 봐요.

원칙의 빈틈은 CI가 막아요

그래프가 있으면 "이런 연결은 있어야 한다"를 검사로 적을 수 있어요. npm run onto -- check가 막는 것들이에요.

  • 모델에 선언하지 않은 DB 칸. 칸마다 왜 저장하는지와 외부 캘린더 대응이 있어야 해요.
  • 선언한 플랫폼에 구현이 없는 앱 정책 규칙, 덮는 시나리오가 없는 규칙.
  • 구현을 시험만 부르는 규칙. 앱은 그 구현을 쓰지 않고 제 나름으로 하고 있다는 뜻이에요.
  • 어느 화면 기능에도 속하지 않은 화면 파일, 한쪽 플랫폼에만 있는데 까닭(differs)도 할 일(todo)도 없는 기능.
  • 파일을 글자로 읽어 규칙을 지키는 시험인데 무엇을 지키는지(@guards) 적지 않은 것.
  • 연결이 가리키는데 실제로는 없는 노드.

그래프도 채점해요

그래프가 그럴듯한 목록을 내놓는다고 맞는 목록은 아니에요. 그래서 사람이 코드를 읽고 확인한 정답지를 뒀어요. 질문 27개에 꼭 나와야 하는 답 32개와 나오면 안 되는 답(지나치게 닿은 것) 10개가 있고, 답마다 근거를 적어요(대개 파일과 줄까지).

{ id: "call-both", ask: "공통 만들기 API를 바꾸면", from: "route:POST /api/v1/items/new",
  want: ["apps/web/lib/client/writes.ts", "apps/ios/Ikie/Model/BoardModel+Outbox.swift"],
  why: "웹 writes.ts와 iOS BoardModel+Outbox.swift(client.createItem)가 부른다" },

정답지에는 그래프가 아직 못 맞히는 질문부터 넣었어요. 그래서 그래프를 고칠 때마다 점수로 잴 수 있어요. 여섯 단계를 거친 결과예요.

맞힌 답틀린 답
숫자로 보기
단계맞힌 답틀린 답
0 · 정답지 만들기10/329
1 · 폼·링크로 부르는 API, 따옴표 친 표 이름 잇기14/32–
2·3 · TypeScript를 이름 단위로27/321
4 · Swift를 tree-sitter로 이름 단위까지26/320
5 · 모델 칸 → 동기화 칸 → 어댑터30/32–
6 · 정책 규칙을 읽는 이름에서 잇기31/320
32문항 정답지로 잰 단계별 점수예요. 틀린 답을 세지 않은 단계는 –로 뒀어요.

지금 맞히지 못하는 하나는 "반복 규칙 칸을 바꾸면 API 문서의 rrule 칸도"예요. 값이 칸에서 칸으로 흘러가는 관계라 "누가 누구에 기대나"를 따라가는 연결로는 나타내지 못해요. 알고 있는 한계로 적어 뒀어요. 맞힌 답이 느는 동안 영향 범위 목록의 평균 크기는 206개에서 108개로 줄었어요. 더 많이 맞히면서 덜 부푼 거예요.

정답지만으로는 우리가 고른 질문에 맞춘 점수일 수 있어요. 그래서 커밋 이력으로도 재요. 지난 커밋에서 한 파일을 바꿀 때 함께 바뀐 파일을 그래프가 영향 범위에 넣었는지 보는 거예요. 견줄 기준도 뒀어요. "전에 두 번 이상 함께 바뀐 파일"을 고르는 단순한 예측이에요.

그래프함께 바뀐 이력(기준)
숫자로 보기
커밋 이력그래프함께 바뀐 이력(기준)
함께 바뀐 파일을 맞힌 비율27%29%
웹 ↔ iOS만28%43%
커밋 약 200개로 잰 비율이에요. 클수록 좋아요.

솔직히 말하면 이력으로는 그래프가 단순한 기준보다 조금 낮아요. 함께 바뀌는 파일 중에는 코드로 서로 기대지 않는 것이 많아서예요(같은 기능의 웹과 iOS 화면, 문서와 시험). 그래서 그래프를 "함께 바뀔 파일 맞히기"로 쓰지 않아요. 그래프는 코드가 실제로 기대는 곳을 빠짐없이 짚는 데 쓰고, 이력 점수는 그래프를 고칠 때 목록이 덜 빠지고 덜 부푸는지 보는 참고로 봐요.

그래프가 찾은 빈틈

  • 정책을 시험만 쓰고 있었어요. "구현을 시험만 부르는 규칙" 검사를 넣은 날 실제 빈틈 셋이 나왔어요. iOS는 판에서 다시 쓸 날을 정책 해석기 대신 제 코드로 견주고 있었어요. 웹은 판 쓰기를 차례로 보내는 줄을 정책에서 읽지 않고 코드에 직접 적어 두었고요. 둘은 앱이 해석기를 부르게 고쳤고, 나머지 하나는 웹에만 필요한 규칙이라 선언을 웹만으로 바로잡았어요.
  • 색과 이동 시간이 어댑터에 닿지 않았어요. 모델의 색 칸을 바꿔도 Google·CalDAV 어댑터가 영향 범위에 나오지 않았어요. 어댑터는 모델 칸이 아니라 동기화 칸 타입을 거쳐 읽거든요. 동기화 칸이 모델 칸을 실어 나른다는 연결을 더하자 닿았어요.
  • 안내에 늘 API가 빠져 있었어요. 훅의 안내가 그래프에 없는 노드 종류로 API를 찾고 있어서, "닿는 API" 줄이 한 번도 나오지 않았어요. 같은 때에 iOS 코드는 화면 기능·정책을 읽는 파일만 그래프에 있어서, API를 바꿔도 그 API를 부르는 iOS 파일이 나오지 않는다는 것도 알았어요.
  • 위젯의 타임라인이 앱의 타임라인으로 이어졌어요. Swift를 이름만 보고 이어서, 위젯이 쓰는 WidgetKit의 Timeline이 앱의 타임라인 화면 파일로 이어지는 식의 틀린 연결이 8개 있었어요. 같은 빌드 타깃에 든 파일끼리만 잇게 바꿨고, 뒤에는 문법 트리로 받는 쪽 타입까지 보게 했어요.

배운 것

규칙을 문서에 적으면 잊히고, 사람이 기억해 지키면 빠져요. 그래프는 원천에서만 지어서 손으로 고칠 사실이 없고, 검사는 원칙의 빈틈을 CI에서 막고, 정답지는 그래프 자체가 맞는지 재요. 셋이 맞물리면 "이것도 같이 봤어요?"를 사람이 기억해서 묻지 않아도 돼요. 고치기 전에는 훅이, 올린 뒤에는 CI가 먼저 말해 주니까요. 그리고 그래프의 점수가 기준보다 낮다는 것도 숨기지 않고 매 PR 보여요. 도구를 믿으려면 도구가 어디서 틀리는지도 알아야 하니까요.

The ikie teamikie is a calendar for your events and to-dos in one place. Here we write about the problems we run into while building it, and how we solve them.