배포 전에 Lighthouse 리그레션을 잡아내는 CLI를 만들었습니다

Source: Dev.to

소개

Google Lighthouse는 일회성 감사를 수행하는 데 뛰어납니다. 하지만 화요일에 LCP를 수정하고 금요일에 번들 회귀를 배포하면, 검색 콘솔이 3주 후에 이메일을 보내기 전까지는 아무도 눈치채지 못합니다.

Lighthouse는 오늘 사이트가 얼마나 빠른지 알려줍니다. kanmi는 속도가 느려질 때를 알려줍니다.

npm install -g @knfrmd/kanmi
kanmi audit https://your-site.com

Kanmi Performance Audit
https://your-site.com
mobile · Slow 4G, 4x CPU · LH 12.0.0 · 14.2s
─────────────────────────────────────────────

Performance      72
Accessibility    95
Best Practices   100
SEO              91

Lab Metrics
─────────────────────────────────────────────
LCP      4,200ms    NEEDS IMPROVEMENT
TBT        380ms    NEEDS IMPROVEMENT
CLS       0.003     GOOD
FCP      1,800ms    GOOD

Top Issues
─────────────────────────────────────────────
* Reduce unused JavaScript (~1.2s savings)
* Eliminate render‑blocking resources (~800ms savings)

한 번의 명령. 점수, 실험실 메트릭, 주요 이슈.

수행하는 작업

• kanmi audit <url> – Lighthouse를 실행하고 결과를 출력합니다.
• kanmi monitor <url> – 3개의 감사를 실행(중간값), 로컬 기록에 저장하고 회귀를 감지합니다.
• kanmi ci – GitHub Actions에서 임계값을 적용하고, 실패 시 exit 1을 반환합니다.

왜 Lighthouse CI가 아닐까?

Lighthouse CI는 강력하지만 다음을 전제로 합니다:

• 서버(LHCI 서버 또는 임시 저장소)
• .lighthouserc.js 프로젝트 설정 파일
• 로컬에서 가치를 보기 전에 CI‑전용 설정

kanmi는 한 명령으로 작동합니다. 서버가 필요 없고, 데이터베이스도 없습니다. ~/.kanmi/history/에 JSON 파일만 저장하고, 자신의 기준선과 자동으로 비교합니다.

What about WebPageTest, Calibre, SpeedCurve?

연속 모니터링 및 실제 사용자 대시보드에 탁월한 도구이지만, 계정, 청구 및 장기 데이터 저장이 필요한 호스팅 서비스입니다.

kanmi는 다른 워크플로우를 위해 설계되었습니다: “이번 배포가 성능을 악화시켰나요?” – 계정 없이도 1분 이내에 로컬에서 답을 얻을 수 있습니다.

Monitoring catches what audits miss

kanmi monitor https://shop.example.com

Kanmi Monitor
Run #8 | 2026-02-28 | 3 runs (median)
─────────────────────────────────────────────

Performance      92  unchanged

Regressions
 CRIT  LCP: 2,100ms -> 2,600ms (+500ms)

Regression Policy
─────────────────────────────────────────────
Baseline     median of last 5 runs
Rule         flag if delta >= max(abs, baseline × rel%)
Fail         exit 1 on critical/high severity

Regression detection uses dual thresholds – 절대 및 상대. LCP는 +150 ms or +10 % 중 더 큰 값으로 플래그를 설정합니다. 이는 느린 사이트에서는 150 ms가 잡음에 불과하므로 오탐지를 방지하고, 빠른 사이트에서는 10 %가 의미가 있으므로 작은 회귀도 포착합니다. 베이스라인 실행이 5번 쌓이기 전까지는 회귀를 평가하지 않아 데이터가 부족한 경우의 잘못된 경보를 피합니다.

CI gate

kanmi ci --urls https://example.com --performance 90

임계값이 실패하거나 중요한 회귀가 감지되면 1을 반환합니다. PR에 주석을 달려면 --post-comment 옵션을 추가하세요.

Source: …

엔지니어링 노트

점수 척도 계약

Lighthouse 점수는 내부적으로 0‑1 범위입니다. 많은 래퍼가 0‑100으로 변환하면서 버그를 일으킵니다. kanmi는 JSON 출력, 저장소, 히스토리 등 모든 곳에서 데이터를 0‑1로 유지합니다. 0‑100 변환은 터미널 표시 레이어에서만 발생하며, CI가 매 푸시마다 검증하는 JSON 스키마에 의해 강제됩니다.

URL 정규화

월요일에 https://www.example.com/?utm_source=email을 모니터링하고 화요일에 https://example.com/을 모니터링한다면, 두 URL은 동일한 기준선에 매핑되어야 합니다. kanmi는 프로토콜, www., 추적 파라미터(14개), 해시 프래그먼트, 기본 포트를 제거한 뒤 저장합니다. 이를 검증하는 단위 테스트 40개가 있습니다.

“Stranger mode” CI

CI 작업은 CLI를 tarball로 패키징하고, 빈 /tmp 디렉터리에 설치한 뒤 바이너리가 실행되고 JSON 출력이 스키마와 일치하는지 검증합니다. 새 설치에서 문제가 발생하면 npm publish 전에 CI가 이를 포착합니다.

시도해 보기

npm install -g @knfrmd/kanmi
kanmi audit https://your-site.com
kanmi monitor https://your-site.com

몇 번 실행하면 회귀 감지가 자동으로 작동하는 것을 볼 수 있습니다.

GitHub: konfirmed/kanmi‑suite