Stella App

Stella 앱 (macOS GUI)

apicov 와 같은 코어를 쓰는 SwiftUI 앱입니다. CLI 로는 불편한 세 가지를 담당합니다.

• 담당자 매핑을 표에서 바로 지정하고 owners.yml · authors.yml 에 반영
• 엔드포인트를 필터링하며 훑어보고 Markdown 으로 복사
• 실제 서버에 요청을 쏴 보는 API 테스트

실행

swift run stella          # 개발 중
open dist/Stella.app      # scripts/build-app.sh 로 만든 번들

화면 구성

사이드바 네 항목으로 나뉩니다 (Sources/StellaApp/ContentView.swift).

항목	내용
설정	스캔 입력값과 담당자 명단 편집
요약	프로젝트별 커버리지 카드
엔드포인트	전체 엔드포인트 표 + 상세 패널
매치 안됨	스펙에 못 붙은 Router case 목록

스캔이 끝나 스냅샷이 생기면 설정 화면에 머물러 있던 선택이 자동으로 요약으로 넘어갑니다. 하단 상태 바에는 진행 상태와 엔드포인트·매치 안됨 개수가 뜹니다.

단축키

키	동작
⌘R	스캔 실행
⌘O	스냅샷 열기
⌘S	스냅샷 저장
⇧⌘S	owners.yml 을 다른 이름으로 저장

설정 화면

OpenAPI 소스

URL 모드와 파일 모드를 세그먼트로 고릅니다.

• URL — 스펙 주소와 Basic 인증 계정. 자동 로그인 을 켜두면 저장된 계정을 스캔 때마다 자동으로 붙입니다. 끄면 계정이 저장돼 있어도 인증 없이 요청합니다
• 파일 — 로컬 JSON 선택

API 테스트

• Base URL — 테스트 요청을 보낼 서버 주소 (기본 https://dev.api.umc.it.kr)
• 토큰 발급 — GET {Base URL}/test/token/access?memberId=1 을 호출해 accessToken 을 받아 채웁니다. 개발 서버 전용 엔드포인트입니다
• Bearer 토큰 — 직접 붙여 넣어도 됩니다. Keychain (kr.it.umc.apicoverage 서비스)에 저장되고 UserDefaults 에는 남지 않습니다

프로젝트

AppProduct · UMCApp · Blame 루트 세 경로. CLI 의 --app-product / --umc-app / --blame-root 와 같은 의미이고 경로 해석 규칙도 같습니다. 최소 한 개의 프로젝트 경로가 필요합니다. 존재하지 않는 디렉터리를 넣으면 스캔 전에 걸러집니다.

매핑 (선택)

authors.yml · overrides.yml · owners.yml 파일 경로. authors.yml 이나 owners.yml 경로를 바꾸면 그 즉시 파일을 다시 읽어 GUI 담당자 상태를 덮어씁니다.

담당자

이메일 · 표시 이름 · GitHub username 으로 명단을 관리합니다. 여기서 저장·삭제하면 설정된 authors.yml 에 바로 기록됩니다.

엔드포인트 화면

필터와 표

• 검색어, 메서드, 연결 상태(전체 / 매치됨 / 누락 / 부분 매치), 태그, 담당자로 걸러냅니다
• 열은 메서드 · 경로 · 요약 · 태그 · 담당자 · 연결 여섯 개. 헤더 우클릭이나 툴바 메뉴로 순서를 바꾸고 폭을 조절할 수 있습니다. 순서·폭은 UserDefaults 에 남습니다
• 행을 선택하고 복사 를 누르면 EndpointCopyFormatter 가 만든 Markdown 이 클립보드에 담깁니다. 파라미터·요청 예시·응답 예시·프로젝트별 연결 상태까지 들어가므로 이슈나 PR 본문에 그대로 붙일 수 있습니다

상세 패널

탭	내용
개요	operationId, 태그, 담당자 지정 Picker, 프로젝트별 연결 정보 (Router case · 파일:줄 · 작성자 · 커밋 SHA)
스펙	파라미터 목록, 요청 바디 요약과 예시, 응답 코드별 설명과 예시 JSON
테스트	Base URL · Bearer 토큰 · Path params · Query · Body 를 채워 실제 요청 실행

테스트 탭의 입력값은 엔드포인트를 바꿀 때마다 스펙 기준으로 다시 채워집니다. 스펙으로 채우기 를 누르면 수동으로 되돌릴 수 있습니다. 이때 page 는 0, size 는 20 으로만 자동 채워집니다. 나머지 파라미터는 빈 값으로 두고 직접 넣습니다. 빈 값은 요청에서 제외됩니다.

응답은 JSON 이면 정렬해서 보여줍니다. 본문 글자 크기는 슬라이더로 조절합니다.

담당자 편집이 파일에 반영되는 규칙

GUI 의 담당자 상태는 UserDefaults 에 살면서 owners.yml · authors.yml 과 다음 규칙으로 오갑니다 (Sources/StellaApp/ScanModel.swift).

• 파일 → GUI: 앱을 켤 때, 그리고 설정 화면에서 authors.yml / owners.yml 경로를 바꿀 때 파일을 읽어 GUI 상태를 덮어씁니다. 스캔 실행이나 스냅샷 열기는 파일을 다시 읽지 않고 현재 GUI 매핑을 결과에 덧입힙니다
• GUI → 파일: 설정에 경로가 채워져 있다면 담당자를 지정하거나 명단을 추가·삭제하는 즉시 해당 파일에 기록됩니다. 경로가 비어 있으면 UserDefaults 에만 남습니다
• ⇧⌘S(owners.yml 저장…) 은 "다른 이름으로 저장"입니다. 저장 패널에서 고른 위치로 내보내고 그 경로를 새 owners.yml 경로로 기억합니다
• 내보낼 때 기존 파일의 tags: 섹션은 보존하고 endpoints: 만 GUI 매핑으로 덮어씁니다. tags: 는 손으로 편집하는 영역입니다
• 팀과 CI 가 보는 진실은 git 에 커밋된 루트 owners.yml 입니다. GUI 로 바꿨으면 커밋해야 반영됩니다

저장되는 값

저장소	내용
UserDefaults	OpenAPI URL·파일 경로, 소스 모드, Basic 계정과 자동 로그인 여부, 프로젝트·blame·매핑 경로, API Base URL, 담당자 명단과 엔드포인트 배정, 표 열 순서·폭, 응답 글자 크기
Keychain (kr.it.umc.apicoverage)	Bearer 토큰

Basic 인증 계정은 UserDefaults 에 평문으로 남습니다. 공용 계정 기준의 선택이므로 개인 계정을 넣었다면 자동 로그인을 끄고 쓰는 편이 안전합니다.

기본 경로 주의

ScanModel.init 은 현재 디렉터리에서 위로 올라가며 AppProduct/ 와 UMCApp/ 이 함께 있는 폴더를 레포 루트로 추정하고 매핑 YAML 기본 경로를 <추정 루트>/Stella/*.yml 로 잡습니다. 분리 전 디렉터리 배치를 그대로 물려받은 값이라 Stella 레포 루트에서 swift run stella 를 띄우면 추정이 빗나갑니다.

첫 실행 때 설정 화면에서 프로젝트·Blame 루트·YAML 경로를 직접 지정하면 UserDefaults 에 저장돼 다음 실행부터 유지됩니다.