lakeday-org/perch

perch – AI 기반 의미적 코드 린트

무엇인가요 – perch는 소스 코드를 스캔하고 의미적 결함(예: 잘못된 호출 순서, 오프셋 1 오류, 환경 변수 오용 등)을 보고하는 명령줄 도구입니다. 분석은 TypeSafe의 대규모 언어 모델 서비스(API 키를 통해 접근)에 의해 구동됩니다. 구문 분석 린터를 넘어서, 모델이 각 메서드의 의도를 추론하고 신뢰도 기반으로 발견 결과를 순위 매깁니다.

작동 방식

• perch scan은 프로젝트를 탐색하고 함수/메서드 그래프를 구축한 후, 간결한 "질문"을 LLM에 전송합니다. 모델은 특정 패턴이 결함일 확률을 반환하며, perch는 이를 심각도 점수(P1, P2, …)로 변환하고 테이블 형태로 출력합니다.
• 결과는 숨김 폴더 .perch/에 캐시되어 반복 실행이 빠릅니다.
• perch issues로 목록을 조회하고, perch issues <id>로 특정 발견 사항을 탐색하며, 수정 후 perch check <id>로 재검사할 수 있습니다.

확장 방법 – 커스텀 룰은 간단한 YAML 형식(perch.yaml 또는 .perch/rules/ 하위 파일)으로 작성합니다. 룰은 다음을 지정합니다:

• where – 파일 글로브 패턴
• each – 세부 granularity(method, function 등)
• min – 문제를 표시하기 위한 최소 신뢰도
• ensure – 원하는 동작을 자연어로 설명

어시스턴트 통합 – perch는 다양한 LLM 어시스턴트(Claude, Codex, Pi, Cursor)용 "스킬"을 설치할 수 있습니다. perch setup <assistant> 명령어는 어시스턴트가 수정 제안에 사용할 수 있는 프롬프트를 포함한 마크다운 파일을 생성합니다.

시작하기

npm install -g @lakeday/perch
export PERCH_API_KEY=$(cat ~/.perch_key)   # console.typesafe.ai에서 획득
perch scan

CLI는 문제 목록, 신뢰도, 발견된 메서드를 테이블 형태로 출력합니다.

일반적인 워크플로우

1. perch scan을 로컬 또는 CI에서 실행합니다.
2. perch issues로 가장 심각한 항목을 검토합니다.
3. 코드를 수정한 후 perch check <id>로 문제 해결 여부를 확인합니다.
4. 거짓 긍정은 .perch/closed.jsonl에 항목을 추가하여 무시합니다.

문서 및 생태계 – 전체 문서는 https://docs.perchscan.com 에 호스팅되어 있으며, 설치, 룰 언어, CI 통합, 내부 "그래프 탐색"에 대해 다룹니다. 프로젝트는 npm(@lakeday/perch)에 게시되었으며, CI 배지, 타입 체크, 단위 테스트를 포함합니다.

성숙도 – 리포지토리는 안정적인 CLI, 자동화된 테스트, CI를 포함합니다. 외부 API 키가 필요하므로 핵심 분석은 TypeSafe 서비스에 의존하지만, 주변 도구(룰 엔진, 캐싱, CI 통합)는 오픈소스입니다.

라이선스 – MIT (see LICENSE).

---

Perch는 자체 프롬프트를 작성하지 않고도 모델 기반의 고수준 코드 품질 검사를 원하는 개발자를 위한 진정한 AI 보강 린트 플랫폼입니다.