whatcable 딥다이브
— 케이블의 숫자를 읽어 병목의 이유를 설명하는 앱

1프로젝트 한줄 요약

whatcable은 USB-C 연결의 상태를 해석하는 네이티브 유틸리티입니다. 메뉴 막대에서 케이블의 속도 등급·허용 전력·연결 장치·충전 협상 정보를 보여주고, CLI에서는 같은 핵심 모델을 텍스트와 JSON으로 내보냅니다. USB-C는 단자의 모양이고, 그 단자로 가능한 통신과 전력 공급의 범위는 별개의 정보입니다.

이 앱의 중심은 숫자 수집 다음에 있습니다. 케이블이 주장하는 능력, Mac이 관측한 연결 상태, 데이터베이스가 알려주는 이름을 구분한 뒤 진단 문장으로 조립합니다. 이 구분을 놓치면 240W 케이블을 꽂았다는 이유만으로 Mac이 지금 240W로 충전 중이라고 잘못 설명하게 됩니다.

1-1. 화면 뒤에서는 네 단계가 이어집니다

1. 수집: macOS의 IOKit과 전원 관련 인터페이스에서 포트·USB-PD·USB·Thunderbolt 상태를 읽습니다.
2. 해독: 정수와 비트 필드를 케이블 속도, 전류 등급, 장치 식별 정보로 바꿉니다.
3. 판단: 충전기·케이블·Mac 또는 연결 장치의 한계와 현재 협상 결과를 비교합니다.
4. 표현: SwiftUI 화면, CLI의 문장, JSON의 구조화된 필드로 결과를 전달합니다.

1-2. 예시 하나로 제품의 목적 이해하기

다음은 이해를 위한 가정입니다. 충전기가 100W를 지원하고 케이블은 60W까지 전달할 수 있다면, 케이블의 정격이 제한 요인이 될 수 있습니다. 반대로 충전기와 케이블에 여유가 있어도 Mac이 적은 전력만 요청할 수 있습니다. 배터리 충전 보류나 완충 상태까지 함께 봐야 설명이 맞아집니다.

코드의 출발점은 Sources/WhatCableCore/Power/ChargingDiagnostic.swift의 init?입니다. 충전 상태를 설명할 근거가 부족하면 객체 생성을 포기하고, 판단할 수 있으면 Bottleneck과 설명 문장을 함께 만듭니다.

2왜 주목받는가

2-1. 흔한 불편과 구체적인 답이 만납니다

USB-C 케이블을 바꿨더니 SSD가 느려지거나, 충전기를 바꿨는데도 충전이 기대만큼 빨라지지 않는 상황은 원인을 짐작하기 어렵습니다. whatcable은 포트별 정보를 모으고 원인 후보를 설명하는 데 집중합니다. 문제 상황을 한 문장으로 말하기 쉽고 결과도 바로 이해하기 쉽다는 점이 관심을 끌 만한 요소입니다.

2026-10-23 GitHub 기준 스타는 8,985, 포크는 274이며, GitHub Trending Swift Weekly #5에 선정됐습니다. 다만 이 수치만으로 방문 경로나 인기의 원인을 증명할 수는 없습니다. 아래의 주목 요인은 기능과 코드 구조를 바탕으로 한 해석입니다.

• 해결하려는 일이 명확합니다. 케이블의 능력과 현재 연결의 제약을 확인한다는 목적이 메뉴 막대 UI와 잘 맞습니다.
• 숫자를 해석해 줍니다. ChargingDiagnostic과 DataLinkDiagnostic이 관측값을 원인별 결과로 바꿉니다.
• 개발자가 가져다 쓸 출력도 있습니다. CLI의 JSON 출력은 화면을 직접 읽지 않고도 결과를 다룰 수 있게 합니다.
• 시스템 프로그래밍의 문턱을 낮춥니다. SwiftUI 화면에서 출발해 IOKit과 비트 해독 코드까지 이어서 읽을 수 있습니다.

2-2. 무엇과 비교하면 차이가 보일까요?

Apple의 시스템 정보 공식 안내에 따르면 시스템 정보 앱은 Mac과 연결 하드웨어 등의 보고서를 보여줍니다. whatcable의 차별점은 그중 케이블 문제에 필요한 신호를 한데 모아 설명하는 흐름입니다. 비교 범위는 도구의 역할이며, 특정 유료 제품의 우열을 검증한 결과는 아닙니다.

이 앱의 장점은 원시 정보를 많이 보여주는 데서 끝나지 않고, 그 정보를 근거가 드러나는 설명으로 바꾸는 데 있습니다. 외부 측정 장비와 달리 Mac이 공개하지 않는 신호까지 직접 측정할 수는 없으므로, 소프트웨어의 관측 범위도 함께 이해해야 합니다.

2-3. 사용자용 제품과 공개 소스의 범위를 나누어 읽기

README는 무료 앱과 별도로 Pro의 전력 모니터, 저장한 케이블 이력, 진단 화면, 터미널 대시보드를 소개합니다. 하지만 커밋 58e588a의 Sources/WhatCablePlugins/Bootstrap.swift는 등록 함수 본문이 비어 있는 4줄짜리 파일입니다.

오히려 학습 주제는 더 선명해집니다. 무료 핵심 기능이 추가 기능에 의존하지 않도록 경계를 어떻게 만들었는가를 살펴보면 됩니다. 4절에서 빈 등록 함수가 왜 의미 있는 설계 흔적인지 설명합니다.

3기술 스택 전체 지도

3-1. 백엔드: 서버 대신 Mac 내부의 데이터 수집 계층

이 프로젝트에서 백엔드라고 부를 만한 부분은 웹 API 서버가 아니라 WhatCableDarwinBackend입니다. macOS에 묶인 읽기 코드를 모아 WhatCableCore의 모델로 전달합니다. 핵심 하드웨어 진단 경로에 별도 서버가 필요한 구조는 아닙니다.

근거는 Package.swift입니다. 제품은 앱·CLI 실행 파일 2개와 라이브러리 3개로 선언됩니다. 알림·플러그인 모듈은 내부 타깃이며, 모든 타깃이 독립 배포 제품인 것은 아닙니다.

3-2. 프론트엔드: SwiftUI와 AppKit의 협업

Sources/WhatCable/App/App.swift의 WhatCableApp은 SwiftUI의 진입점입니다. @NSApplicationDelegateAdaptor로 AppDelegate를 연결하고, 실제 메뉴 막대 항목·팝오버·일반 창의 수명은 AppKit 쪽에서 관리합니다. 카드 내용은 Sources/WhatCable/Views/ContentView.swift 등 SwiftUI 코드가 그립니다.

이 코드는 상태 구독에 ObservableObject 계열을 사용합니다. 최근 Swift 예제에서 보이는 @Observable로 이미 바뀌었다고 읽으면 안 됩니다. 학습할 때도 저장소의 선언과 다른 버전의 문법을 구분하세요.

3-3. 의존성 선언과 잠금 파일을 함께 읽는 이유

Package.swift에는 외부 .package(...) 의존성 선언이 없습니다. 그런데 Package.resolved에는 TUIkit의 main 브랜치와 리비전 18246360bbdefd5ad7e5eab47955d47eac9d824f가 남아 있습니다. 이것만으로 공개 앱이 현재 TUIkit을 사용한다고 결론 내릴 수 없습니다.

3-4. 웹사이트와 인프라·빌드

루트의 package.json은 Mac 앱이 아니라 whatcable.uk의 정적 사이트용입니다. eleventy.config.js가 Nunjucks 자료를 처리하고 src/에서 docs/를 생성합니다. 이 src/는 저장소 내부 웹사이트 폴더이며 Swift 앱 코드는 Sources/에 있습니다.

버전의 근거는 package.json과 bun.lock입니다. 워크플로는 actions/checkout@v4, oven-sh/setup-bun@v2, actions/configure-pages@v5, actions/upload-pages-artifact@v3, actions/deploy-pages@v4를 사용합니다. Bun 자체 버전은 이 설정에서 고정하지 않습니다.

Mac 앱의 빌드 환경과 사이트의 빌드 환경은 서로 다르므로, 루트에 JavaScript 의존성이 있다는 이유로 앱을 웹 기술 기반이라고 분류하면 안 됩니다. 공개 워크플로에서 확인되는 자동 배포는 Pages용이며, 앱 릴리스 과정은 별도 셸 스크립트에 담겨 있습니다.

4아키텍처 심화 분석

4-1. 전체 시스템 구조

구조도의 핵심은 앱과 CLI가 같은 창을 공유한다는 뜻이 아니라, 같은 도메인 모델과 해석 코드를 재사용한다는 점입니다. UI의 상태를 CLI가 몰래 읽는 대신 각 실행 경로가 하드웨어 데이터를 얻고 핵심 모델에 전달합니다. 위젯도 갱신 시점과 수명이 별도입니다.

4-2. 패턴 ① 수집 경계와 스냅샷: 읽는 방식이 달라도 판단은 재사용

WhatCableCore의 CableSnapshotProvider는 데이터를 얻는 두 가지 동작만 약속합니다. 현재 상태 하나를 얻는 snapshot()과 상태 변화를 받는 watch()입니다. 아래는 Sources/WhatCableCore/Snapshot/CableSnapshot.swift의 선언입니다.

public protocol CableSnapshotProvider: Sendable {
    func snapshot() async throws -> CableSnapshot
    func watch() -> AsyncThrowingStream<CableSnapshot, Error>
}

DarwinSnapshotProvider가 이 약속을 macOS용으로 구현합니다. makeDefaultSnapshotProvider()는 구체 구현을 any CableSnapshotProvider로 돌려주고, CLI는 그 공급자에게 요청합니다. 읽기 장치를 테스트용 가짜 구현으로 바꿔볼 수 있는 경계가 생깁니다.

DarwinSnapshotProvider.swift의 watch()는 매번 읽기 뒤 1초를 기다리며, 이전 CableSnapshot과 다를 때만 스트림에 내보냅니다. onTermination에서는 내부 Task를 취소합니다. CLI 변경 감시의 수명을 명시적으로 닫는 부분입니다.

이 경계가 모든 동시성 문제를 자동으로 해결하지는 않습니다. 해당 클래스는 @unchecked Sendable을 선언하고 내부 State는 @MainActor로 격리합니다. 또 CableSnapshotContext의 주석은 CableSnapshot이 아직 Sendable이 아니라고 밝힙니다. “프로토콜이 Sendable이니 모든 반환값도 안전하다”고 일반화하면 안 됩니다.

4-3. 패턴 ② 읽기와 적용 분리: 늦게 끝난 결과가 최신 상태를 지우지 않게

앱의 WatcherHub.swift는 watcher들을 한곳에서 소유합니다. requestRefresh(steady:)가 읽기를 요청하고, HubRead.readAll(_:smcReader:)이 결과 묶음을 만든 다음, apply(_:readStartedAt:)가 상태에 반영합니다.

버스트의 대기값은 순차적으로 더해집니다. 읽기 시간과 스케줄링 지연을 제외하면 시작 후 약 0.15·0.65·2.15·5.15·11.15초에 요청하는 셈이며, 연결 사건에서 각 숫자만큼 떨어진 절대 시각을 뜻하지 않습니다.

포트를 읽는 동안 케이블이 빠지면 어떤 일이 생길까요? 알림으로 watcher가 먼저 최신 상태를 게시하고, 뒤늦게 끝난 읽기가 이전 연결을 다시 덮어쓸 수 있습니다. 이 앱은 비동기 읽기에 참여하는 watcher의 refreshGeneration을 읽기 시작 때 기록해 두고, 적용할 때 여전히 같은지 검사합니다.

// WatcherHub.apply(_:readStartedAt:)에서 발췌
if portWatcher.refreshGeneration == start.port {
    portWatcher.apply(reading.ports)
} else {
    skipped = true
}
// 생략된 다른 watcher 검사 뒤에 이어지는 처리
if skipped { followUpQueued = true }

메인 액터에서 상태를 바꾸더라도, 비동기 읽기가 시작된 뒤 더 최신 정보가 도착할 수 있으므로 결과의 신선도를 별도로 검사해야 합니다. 상태 접근의 안전성과 데이터의 최신성은 서로 다른 문제입니다.

정기·버스트 갱신의 공유 읽기는 Task.detached(priority: .userInitiated)에서 수행하고 적용은 메인 액터로 돌아옵니다. 다만 start()의 초기 포트·PD·전원 갱신은 메인 액터에서 동기적으로 처리합니다. CLI 공급자도 이 앱용 스케줄러와 다른 읽기 경로를 사용합니다.

읽기 순서에도 이유가 있습니다. HubRead.readAll(_:smcReader:)은 포트 → PD 식별 → 전원 순서로 읽습니다. 전원 노드가 없는 일부 환경에서 만드는 보완 정보가 이번 읽기의 포트와 PD 식별에 의존하기 때문입니다. 독립적이지 않은 읽기를 무작정 병렬화할 수 없는 사례입니다.

4-4. 패턴 ③ 공통 키로 결합하고, 정보의 출처는 보존

하나의 물리 포트도 USB 장치 목록, 충전 정보, PD 응답, Thunderbolt 정보에서는 다른 자료로 등장합니다. PortIdentity는 typeCode와 number를 묶고 "2/1" 같은 키를 만듭니다. 코드의 USB-C 타입 값은 0x2, MagSafe 3는 0x11입니다.

CableSnapshotContext.init(snapshot:)은 포트마다 충전원·PD 식별·USB 전송·CIO·화면 정보를 모읍니다. 장치 목록에서는 직접 매칭된 장치와 구조상 이 포트에 속하는 터널 장치를 합치되, Set<UInt64>로 중복 식별자를 제거합니다.

이때 e-marker가 보고하는 제조사 식별자는 칩 공급자와 관련될 수 있습니다. CableDB.curatedCables(vid:pid:cableVDO:)는 VID·PID에 더해 Cable VDO 변형을 비교하며, 한 지문에 여러 판매 브랜드가 연결될 수 있음을 고려합니다. 제조사 ID 하나로 소매 제품명을 단정하지 않는 것입니다.

출력의 bulletGroups도 학습할 부분입니다. 골든 JSON은 source를 emarker, measured, database, charger 등으로 구분합니다. 화면에 비슷하게 보이는 한 줄들이 어떤 근거에서 왔는지 모델 수준에서 나눕니다.

4-5. 패턴 ④ 등록 객체를 통한 확장: 추가 기능이 없어도 핵심은 유지

Sources/WhatCableAppKit/PluginRegistry.swift는 메뉴 항목, 카드의 추가 뷰, 위젯 데이터 제공자, CLI 명령 등을 배열에 등록합니다. 앱과 CLI는 등록된 항목을 소비합니다. 추가 기능의 구체 타입을 핵심 화면이 직접 알아야 하는 구조를 피합니다.

// Sources/WhatCablePlugins/Bootstrap.swift 전체
import WhatCableAppKit

public func bootstrapPlugins(registry: PluginRegistry) {
}

빈 함수도 호출 경계를 유지합니다. 공개판에서는 등록된 Pro 명령이 없고, 추가 구현을 연결하는 판본에서는 같은 지점에 기능을 등록할 수 있습니다. 다만 이것은 앱 내부의 등록 방식입니다. 임의의 외부 바이너리 플러그인을 실행 중에 찾아 불러오는 시스템이라고 설명할 근거는 없습니다.

CLI의 main()은 등록된 명령의 플래그를 기존 플래그 집합에 합친 뒤 알 수 없는 인수를 검사합니다. 등록된 플러그인 명령 두 개가 동시에 매칭되면 오류로 처리합니다. 확장 가능한 구조에서도 사용자 입력의 모호함을 방치하지 않는 사례입니다.

5디렉토리 구조 해부

5-1. Swift 코드의 무게중심

커밋 58e588a의 텍스트 파일을 줄 단위로 세면 다음과 같습니다. 공백·주석을 포함한 물리적 줄 수이며 복잡도나 실행 성능의 척도는 아닙니다. Swift 전체는 422개 파일, 약 147,961줄입니다.

핵심 모듈에는 생성된 EDIDTimingTables.generated.swift 329줄도 포함됩니다. 테스트가 구현보다 길다는 사실은 다양한 하드웨어 사례와 회귀 조건을 많이 기술한다는 단서입니다. 테스트가 모두 실행되거나 통과한다는 증거로 사용할 수는 없습니다.

5-2. 다른 언어도 역할별로 세어야 합니다

JavaScript를 전부 합하면 130,310줄이지만, 여기에는 배포 결과 쪽의 사본과 동봉 라이브러리가 들어갑니다. 앱의 규모를 그 숫자로 설명하면 구조를 잘못 전달하게 됩니다. 줄 수를 볼 때는 언어뿐 아니라 원본·생성물·외부 코드의 경계도 확인하세요.

5-3. 초보자를 위한 읽기 순서

1. Package.swift로 모듈 이름과 화살표를 적습니다.
2. Sources/WhatCableCore/PD/USBPDVDO.swift와 Tests/WhatCableCoreTests/PDVDOTests.swift를 나란히 읽습니다.
3. Sources/WhatCableCore/Power/ChargingDiagnostic.swift에서 입력과 결과 enum을 연결합니다.
4. Sources/WhatCableCore/Snapshot/CableSnapshotContext.swift로 입력들이 포트별로 모이는 과정을 봅니다.
5. Sources/WhatCableDarwinBackend/Watchers/HubRead.swift와 WatcherHub.swift로 실제 수집·갱신을 이해합니다.
6. 마지막으로 WhatCableCLI.swift와 ContentView.swift에서 사용자까지의 경로를 확인합니다.

6학습 포인트 (기술별)

6-1. Swift 비트 연산: 정수 하나 안의 여러 필드 꺼내기

PDVDO.decodeIDHeader(_:)는 32비트 정수에서 서로 다른 필드를 분리합니다. 아래 두 줄은 실제 코드의 식을 학습용 변수에 대입한 예입니다. 하위 16비트는 공급자 ID, 29~27번 비트는 UFP 제품 유형입니다.

let vdo: UInt32 = 0x1800_1234
let vendorID = Int(vdo & 0xFFFF)               // 0x1234
let productType = Int((vdo >> 27) & 0b111)    // 3

// 별도의 Cable VDO에서 속도·전류 필드만 연습한 값
let cableVDO: UInt32 = (2 << 5) | 4
let speedBits = Int(cableVDO & 0b111)           // 4
let currentBits = Int((cableVDO >> 5) & 0b11)   // 2

실습 아이디어: 종이에 32칸을 그리고 0x1800_1234의 필드를 분리해 보세요. 그다음 PDVDOTests.decodePassiveCableIDHeader()와 답을 비교합니다. 같은 숫자 3도 UFP에서는 수동 케이블, DFP에서는 전원 공급 장치이므로 필드의 맥락을 빼면 잘못 해독하게 됩니다.

위 예시의 cableVDO는 속도·전류 필드만 구성한 연습값이며 완전한 케이블 응답은 아닙니다. 실제 함수는 이 밖의 필드도 검사합니다. 파일 맨 위 주석은 PD 3.0/3.1 해독이라고 소개하지만, 세부 주석은 R3.2 표를 인용합니다. CableSpeed.usb4Gen3 주석은 일부 규격 판본 사이의 속도 인코딩 해석이 모호하다는 점도 남깁니다. 상단 요약만으로 모든 필드의 규격 판본과 해석이 확정됐다고 읽지 마세요.

6-2. enum과 실패 가능한 초기화: 모르는 상태를 자료형으로 표현

DataLinkDiagnostic.Bottleneck은 fine, cableLimit, hostLimit, deviceLimit, degraded, unknownCable, cableContradictsActive, blockedBySecurity를 구분합니다. 각 상태는 필요한 숫자를 연관값으로 가집니다.

// DataLinkDiagnostic.Bottleneck의 일부
case cableLimit(cableGbps: Double, capableGbps: Double)
case degraded(activeGbps: Double, expectedGbps: Double)
case unknownCable(activeGbps: Double)
case cableContradictsActive(cableGbps: Double, activeGbps: Double)

케이블 능력을 모르는 것과 연결이 기대보다 느린 것은 다릅니다. 읽힌 속도와 e-marker의 주장이 충돌하는 경우도 별도 상태입니다. 알 수 없음을 정상적인 결과로 모델링하면, 근거가 부족한데도 사용자에게 잘못된 원인을 지목하는 일을 줄일 수 있습니다.

실습 아이디어: DataLinkDiagnosticTests.swift의 degradedLink()와 unknownCableWhenNoSignal()을 비교하세요. “현재 속도” 외에 어떤 능력 정보가 있어야 더 강한 판단을 할 수 있는지 입력 표로 정리합니다.

6-3. 진단 결과와 경고 강도는 별개입니다

DataLinkDiagnostic.isWarning은 fine, deviceLimit, unknownCable을 경고로 표시하지 않습니다. 느린 USB 장치가 자신의 최고 속도로 동작하는 것은 케이블 고장이 아니기 때문입니다. 충전 쪽 ChargingDiagnostic.isWarning의 현재 구현은 cableLimit만 true입니다.

여기에는 작은 주석 불일치도 있습니다. 데이터 진단 파일의 설명에는 충전 진단은 fine만 비경고라는 비교가 남아 있지만, 실제 충전 진단의 switch는 그보다 넓게 비경고를 처리합니다. 동작을 설명할 때는 실행 분기를 우선 근거로 삼아야 합니다.

실습 아이디어: 상태 이름만 보고 빨간색을 고르지 말고 “사용자가 케이블을 바꾸면 해결되는 문제인가?”라는 질문으로 경고 여부를 따로 정리하세요. UI의 색과 문구도 도메인 정책의 일부임을 배울 수 있습니다.

6-4. SwiftUI 상태: 화면에 필요한 정보와 그 정보의 수명

ContentView는 @ObservedObject로 공유 watcher를 관찰하고, 내부에서 소유하는 ConnectionFaultTracker는 @StateObject로 보관합니다. 일반 값인 PortVisibilityTracker는 @State로 유지합니다. 구독과 소유, 값의 지속성을 서로 다른 선언으로 나타냅니다.

앱 진입점의 WhatCableApp.startUp(defaults:applyLanguage:bootstrap:)은 언어 적용을 플러그인 등록보다 먼저 합니다. 번역 문자열로 메뉴 제목을 만드는 시점 전에 언어를 확정해야 첫 화면부터 맞게 표시되기 때문입니다.

실습 아이디어: ContentView.swift에서 속성 래퍼 세 종류를 찾아 “누가 객체를 만들고, 뷰가 다시 만들어져도 무엇이 남아야 하는가”를 설명해 보세요. SwiftUI 공식 문서는 선언형 화면과 상태 관리 개념을 더 찾아볼 출발점입니다.

6-5. IOKit과 자원 수명: 반복 중에도 하드웨어는 바뀝니다

IOKitHelpers.swift의 wcDrainAllRetrying<T>는 IOKit iterator를 끝까지 읽습니다. 항목을 하나 이상 읽은 뒤 iterator가 무효화됐고 시도 횟수가 남아 있으면, 그 회차의 결과를 버리고 처음부터 다시 읽습니다. 기본 시도 횟수는 maxAttempts = 3입니다. 마지막 시도에서도 무효하면 그 회차에서 모은 결과를 그대로 반환하므로 일부 항목이 빠질 수 있습니다. 처음부터 빈 목록은 재시도하지 않습니다.

이 함수는 각 항목을 변환한 뒤 IOObjectRelease(next)로 반환합니다. Swift의 일반 객체처럼 보이는 코드에서도 C 계열 시스템 자원의 수명을 따로 관리해야 하는 이유가 드러납니다. 자세한 경계는 해당 소스 파일과 Apple의 IOKit 문서를 함께 보세요.

실습 아이디어: 첫 시도에서 장치 A를 읽은 직후 무효화되고, 다음 시도에서 A와 B를 읽는 경우를 적어보세요. 첫 회차 결과를 버리지 않으면 A가 중복되는 이유를 설명할 수 있어야 합니다.

6-6. SQLite와 데이터 식별: 이름 하나 붙이기도 조심스럽게

CableDB는 Bundle.module의 whatcable.db를 SQLITE_OPEN_READONLY | SQLITE_OPEN_NOMUTEX로 열고, 자료를 메모리 딕셔너리로 옮긴 뒤 핸들을 닫습니다. 정적인 번들 자료를 반복 조회하는 용도이며 변경 이력을 저장하는 사용자 DB와는 다릅니다.

curatedCables(vid:pid:cableVDO:)는 VID나 PID가 0이면 빈 배열을 돌려줍니다. VID·PID가 맞는 후보 안에서 VDO가 정확히 같은 행을 우선하고, 없으면 VDO가 0인 미지정 행으로만 돌아갑니다. 사양이 다르다는 이유로 엉뚱한 브랜드를 붙이지 않도록 검색 범위를 제한합니다.

실습 아이디어: 같은 VID·PID에 3A·5A 두 행을 그려 놓고 VDO 일치, 미일치, 미지정 경우의 결과를 예상해 보세요. Tests/WhatCableCoreTests/CableDBVariantLookupTests.swift와 연결됩니다.

6-7. 테스트: 정상 예제보다 틀리기 쉬운 경계를 먼저 읽기

테스트는 import Testing, @Suite, @Test, #expect를 사용하는 Swift Testing 코드가 다수입니다. 비트 해독 테스트는 장치 없이 입력 정수만으로 기대 결과를 기술할 수 있습니다. 반면 하드웨어 코퍼스 재생 테스트는 별도 자료의 유무까지 확인해야 합니다.

// PDVDOTests의 입력과 핵심 검사를 줄인 예
let vdo: UInt32 = 0x1800_0000 | 0x1234
let header = PDVDO.decodeIDHeader(vdo)
#expect(header.ufpProductType == .passiveCable)
#expect(header.vendorID == 0x1234)

Tests/WhatCableDarwinTests/WatcherHubTickTests.swift는 가짜 읽기를 주입해 메인 스레드 밖의 읽기, 요청 합치기, 상태 반영을 검증하도록 작성돼 있습니다. 실제 케이블을 뽑는 타이밍에 의존하지 않고 경합을 재현하는 설계입니다.

실습 아이디어: 테스트 이름을 입력 조건과 기대 결과로 바꿔 읽어보세요. 마지막으로 Tests/WhatCableCoreTests/Fixtures/golden/의 JSON·텍스트 쌍을 비교하면, 같은 판단을 여러 출력으로 일관되게 전달하는 계약도 배울 수 있습니다.

7하드웨어 / 시스템 요구사항

7-1. 앱 사용과 소스 학습의 조건

README의 빌드 안내는 Swift 5.9+ (Xcode 15+)라고 적지만, 현재 테스트는 Swift Testing을 사용합니다. Apple은 Xcode 16 이상에 Swift Testing이 포함됨을 안내합니다. 따라서 README의 옛 최소 안내만 보고 이 커밋의 전체 테스트 환경이 충족된다고 판단하면 안 됩니다.

7-2. Universal 바이너리와 Intel 지원을 혼동하지 않기

scripts/smoke-test.sh는 앱과 CLI를 --arch arm64 --arch x86_64로 빌드합니다. 위젯 빌드에도 아키텍처 재정의를 전달합니다. 반면 project.yml의 기본값은 ARCHS: arm64입니다. 설정 파일의 기본값과 배포 스크립트의 최종 인수가 다릅니다.

Intel용 실행 코드가 들어 있다는 사실과, Intel Mac에서 케이블 진단에 필요한 하드웨어 정보가 나온다는 사실은 별개입니다. CLI는 실제 하드웨어를 확인해 Intel에서는 포트 컨트롤러 데이터가 없다는 경고를 보냅니다. Rosetta의 실행 아키텍처만 보고 판단하지 않도록 런타임 확인을 합니다.

예외도 있습니다. --tb-debug 경로는 Thunderbolt 패브릭 정보가 Intel에서도 유용할 수 있어 같은 경고를 적용하지 않습니다. 지원 범위를 “Intel에서는 어떤 정보도 없다”로 넓혀 쓰면 소스의 의도를 놓칩니다.

7-3. 권한·배포·위젯의 현실적인 경계

README는 Developer ID 서명과 Apple 공증을 거친 배포를 설명합니다. 소스의 배포 경로는 서명·공증·Gatekeeper 검증을 다루지만, 인증서와 공증 설정 없이 만든 개발판이 같은 배포 상태가 되는 것은 아닙니다. 앱을 실행할 수 있는 최소 OS와 개발 도구를 실행할 수 있는 OS도 서로 다른 조건입니다.

README의 “private API를 쓰지 않는다”는 설명도 범위를 나눠 읽어야 합니다. 소스는 IOKit 접근과 Apple의 서비스 클래스·속성 이름 해석에 의존합니다. 공개 IOKit 접근 함수를 사용한다는 사실이 모든 서비스 속성의 영구적인 호환성을 보장하지는 않습니다.

CableTimelineProvider.swift는 포트 상태를 직접 읽고, 포트 목록을 얻지 못하면 앱이 저장한 App Group 자료를 사용합니다. 충전 상태는 기록 후 120초 이내인 앱 캐시를 우선하며, 그런 캐시가 없으면 SMC에서 읽습니다. 위젯이 메뉴 막대 화면처럼 매초 계속 실행되는 것은 아닙니다. Apple의 위젯 갱신 문서도 타임라인과 시스템의 갱신 예산을 설명합니다.

8직접 해볼 수 있는 실습 과제

다섯 과제는 순서대로 난도가 올라갑니다. 먼저 종이와 편집기로 답을 적고, 해당 테스트와 구현을 대조하세요. 실습의 완성 기준은 결과를 맞히는 데서 끝나지 않고, 어떤 근거가 부족하면 판단을 보류해야 하는지 설명하는 것입니다.

{
  "ports": [{
    "cable": { "maxWatts": 240 },
    "charging": { "bottleneck": "fine" },
    "powerSources": [{
      "negotiated": { "powerW": 100 }
    }]
  }]
}

위 상자는 키의 위치만 보여주는 축약입니다. 전체 자료 구조를 확인할 때는 저장소의 실제 .json 파일을 기준으로 삼으세요.

9관련 기술 심화 학습 로드맵

9-1. 선수 지식이 부족할 때의 우회로

Swift가 처음이라면 1주차를 두 번 반복해도 괜찮습니다. 먼저 let, struct, enum, guard, if let을 익히고 2주차로 넘어가세요. IOKit 함수 이름을 전부 외우는 것보다, 함수가 받아들이는 입력과 만들 수 있는 결과의 범위를 설명하는 능력이 먼저입니다.

작은 해독 함수의 입력과 출력을 이해한 뒤 그 입력이 어디서 오고 언제 바뀌는지 추적하면, 시스템 코드도 단계적으로 읽을 수 있습니다. 처음부터 14만 줄 전체를 이해하려고 할 필요는 없습니다.

9-2. 다음 학습으로 연결할 질문

• Swift 동시성: @MainActor가 막는 문제와 세대 번호가 막는 문제는 어떻게 다른가?
• 자료 모델링: 선택값 nil을 0으로 바꾸면 어떤 판단 근거가 사라지는가?
• 데이터 결합: 표시 이름 대신 안정적인 식별 키로 결합해야 하는 이유는 무엇인가?
• 실패 처리: 한 번의 읽기가 불완전할 때 재시도·보류·경고 중 무엇을 선택할 것인가?
• 제품 설명: 관측, 자기 보고, DB 지식을 사용자에게 어떻게 구별해 보여줄 것인가?

10핵심 키워드 사전

11참고 링크

11-1. 저장소와 제품

• 공식 저장소 darrylmorley/whatcable — 프로젝트 안내와 이슈·릴리스의 출발점
• 분석 기준 커밋의 전체 트리 — 이 글에서 인용한 소스 판본
• 해당 커밋의 README — 제품 기능, 설치·빌드 안내, 하드웨어 지원 설명
• v1.5.0 릴리스 — 2026-10-13 발표 판본
• 공식 웹사이트 — 사용자 기능 소개와 설명 자료
• 라이선스 원문 — 루트의 기본 조건과 하위 경로 예외 설명

11-2. 구현을 다시 확인할 핵심 경로

• Package.swift — 제품과 타깃의 실제 의존 관계
• PDVDO 해독 코드와 대응 테스트 — 정수와 의미의 연결
• DataLinkDiagnostic — 정보가 부족하거나 충돌하는 경우의 판단
• CableSnapshotContext — 포트별 결합과 e-marker 선택 범위
• WatcherHub와 읽기 조율 테스트 — 요청 합치기와 결과 적용
• smoke-test.sh — 버전·아키텍처·번들·서명 검증의 연결
• Pages 워크플로 — 네이티브 앱과 별개인 사이트 배포

11-3. 관련 기술 공식 문서

• Swift 언어 가이드 — 값 타입·enum·선택값·비트 연산과 동시성
• SwiftUI와 AppKit — 선언형 화면과 Mac 앱 수명·창 관리
• IOKit — 시스템 객체와 장치 인터페이스 접근
• WidgetKit 갱신 모델 — OS가 관리하는 타임라인과 갱신 정책
• Xcode 테스트 문서 — Swift Testing과 XCTest의 역할
• USB-IF의 USB Power Delivery 규격 안내 — VDO·PDO를 읽을 때 판본을 대조할 공식 출발점
• SQLite C API 소개 — 시스템 SQLite3로 번들 자료를 읽는 방식을 더 공부할 때
• Eleventy 문서 — 정적 사이트 파이프라인을 별도 주제로 확장할 때

규격 안내 페이지의 최신 판본과 코드가 인용한 판본은 다를 수 있습니다. 코드의 주석에 적힌 표 번호, 실제 비트 위치, 회귀 테스트를 함께 대조하세요. 이 글의 판단 로직 설명은 커밋 58e588a의 구현을 기준으로 합니다.

현재 상태 (2026-10-23 확인)