What JAM answers
“프로덕션에 올려도 되는 코드인가?”를 정적 근거로 빠르게 좁힙니다.
JAM은 테스트 실행기나 SCA 도구를 대체하지 않습니다. 대신 빌드 없이 항상 측정 가능한 정적 코드 건강도 기준선을 만들고, 필요할 때 외부 test/security CLI를 붙여 full 점수로 승격합니다.
AI Agent 산출물 리뷰
큰 파일, 깊은 중첩, 복제된 함수, 위험한 문자열 조합처럼 리뷰 전에 걸러야 할 신호를 file:line으로 모읍니다.
PR 품질 게이트
--fail-under, --strict, SARIF 업로드로 점수 하락과 파스 실패를 CI에서 막습니다.
품질 회귀 추적
jam diff와 deterministic CSV로 finding 증감, category score 변화, 신규 debt를 비교합니다.
프로덕션 준비도 합성
jam full이 test-cli/security-cli 결과를 읽어 품질 실패와 측정 인프라 실패를 분리합니다.
Official distribution
공식 바이너리는 jhl-labs/dist GitHub Release에서 배포합니다.
설치 스크립트는 현재 OS/아키텍처에 맞는 단일 실행파일을 받고 SHA256SUMS로 검증합니다.
Windows는 release asset을 직접 내려받아 PATH에 두면 됩니다.
한 줄 설치
기본 설치 위치는 /usr/local/bin/jam입니다. CI에서는 VERSION=v0.46.0로 고정할 수 있습니다.
curl -fsSL https://jhl-labs.github.io/jam/install.sh | sudo bash
curl -fsSL https://jhl-labs.github.io/jam/install.sh | sudo env VERSION=v0.46.0 bash
Quickstart
기본은 jam-lite, 필요한 컴포넌트만 jam-full로 확장합니다.
정적 스캔
소스 파일을 발견하고 언어별 경량 프론트엔드로 함수, import, 토큰, finding 후보를 추출합니다.
점수화
finding debt를 category TDR로 정규화하고 grade cap, confidence, suppress 규칙을 적용합니다.
증적 출력
리뷰용 Markdown, 집계용 CSV/JSON, 코드 스캔 UI용 SARIF를 같은 실행에서 생성합니다.
Full 합성
옵션으로 test-cli/security-cli를 호출해 test/security 점수와 실패 원인을 합성합니다.
로컬 품질 스캔
--strict를 사용합니다.
jam lite . --json --sarif --strict --out reports/jam
Full 전체 게이트
jam-full.json을 생성합니다.
jam full . --out reports/jam-full
Full 보안 보강
jam full . --component security --out reports/jam-security
Metrics v14.5.0
jam-lite는 이 CLI만으로 측정 가능한 37개 정적 지표를 모두 구현합니다.
지표는 점수 범위와 함께 봐야 합니다. jam-lite는 유지보수성에는 강하지만, 정확성·성능·런타임 동작을 증명하지는 않습니다.
jam-lite가 말하는 것과 말하지 않는 것
jam-lite 점수는 "이 코드가 옳은가"가 아니라 "이 코드 위에 계속 쌓아도 되는가"에 대한 정적 신호입니다. 상세한 범위와 한계는 커버리지와 한계에서 정리합니다.
| ID | 목적 | 산출 | 해석 |
|---|---|---|---|
| SIZE-01 | 리뷰하기 어려운 대형 파일 찾기 | 파일별 코드 라인 수 | 파일이 클수록 이해·변경 비용 증가 |
| SIZE-02 | 너무 긴 함수 찾기 | 함수 라인 수 | 긴 함수는 분리와 테스트 경계 검토 대상 |
| SIZE-03 | 넓은 함수 인터페이스 찾기 | 파라미터 개수 | 데이터 뭉치나 책임 과다 신호 |
| SIZE-04 | 책임이 몰린 파일·타입 찾기 | 선언 수, 참조 집중도, 메서드/필드 수 | God file/type 후보 |
| CPLX-01 | 테스트 경로가 많은 함수 찾기 | 순환 복잡도(CCN) | 분기와 예외 경로가 많을수록 위험 |
| CPLX-02 | 사람이 읽기 어려운 흐름 찾기 | 인지 복잡도 | 중첩과 제어 흐름 부담을 반영 |
| CPLX-03 | 깊은 들여쓰기 찾기 | 최대 블록 중첩 깊이 | 가독성과 빠른 리뷰를 방해하는 위치 |
| CPLX-04 | 어휘량이 큰 코드 찾기 | Halstead Volume | 직접 감점보다 유지보수성 보조 입력 |
| CPLX-05 | 파일 유지보수성 요약 | Maintainability Index | 낮을수록 읽고 고치기 어려움 |
| ARCH-01 | 모듈 순환 의존 찾기 | import graph SCC와 cycle path | 변경 전파와 빌드/테스트 비용 증가 |
| ARCH-02 | 같은 모듈 안 파일 얽힘 찾기 | 파일 수준 심볼 참조 cycle | 응집도와 파일 분리 검토 신호 |
| ARCH-03 | 과결합·불안정 의존 찾기 | Ca, Ce, Instability, SDP 위반 | 핵심 모듈이 흔들리는 변경 위험 |
| ARCH-04 | 평탄 구조와 죽은 내부 모듈 찾기 | 디렉터리 파일 수, orphan module | 모듈 경계 재정리 후보 |
| ARCH-05 | 허브형 의존(God Component) 찾기 | Ca·Ce 동시 outlier + 절대 하한 | 많은 것에 의존하며 많은 것이 의존하는 병목 |
| ARCH-06 | 변경 파급 비용 측정 | 전이적 의존(가시성 행렬) 밀도 | 작은 변경이 시스템 전체로 퍼지는 정도 |
| ARCH-07 | 낮은 응집도(LCOM4) 찾기 | 타입 메서드의 상태 공유 연결요소 수(tree-sitter) | 한 타입에 무관한 책임이 묶인 신호 |
| ARCH-08 | 깊은 상속(DIT) 찾기 | 프로젝트 내부 상속 체인 깊이(tree-sitter) | 동작이 여러 조상에 분산돼 이해·변경 어려움 |
| DUP-01 | 복사-붙여넣기 중복 블록 찾기 | 정규화 토큰 중복률 | 수정 누락과 결함 전파 위험 |
| DUP-02 | 조금 바뀐 유사 함수 찾기 | 함수 토큰 유사도 | 중복 추상화 또는 의도적 분기 검토 |
| SEC-01 | 하드코딩 시크릿 찾기 | 고엔트로피 문자열, 알려진 토큰 형식 | 즉시 제거해야 할 노출 위험 |
| SEC-02 | 인젝션 위험 문자열 결합 찾기 | 위험 sink 주변 문자열 조립 패턴 | SQL/command/HTML 주입 가능성 |
| SEC-03 | 약한 암호·TLS 설정 찾기 | 취약 crypto, 난수, TLS verify off | 보안 기본값 위반 신호 |
| SEC-04 | 위험 역직렬화·동적 실행 찾기 | eval, unsafe YAML/pickle, shell exec sink | 원격 실행·데이터 변조 위험 |
| SEC-05 | 민감 정보 로깅 찾기 | 로그 인자 내 password/token/secret 식별자 | 운영 로그를 통한 정보 노출 위험 |
| SEC-06 | DOM XSS 찾기 | dangerouslySetInnerHTML/innerHTML= 등 비리터럴(JS/TS) | 살균 없는 값이 DOM에 들어가는 XSS 경로 |
| SEC-07 | 경로 조작(Path Traversal) 찾기 | 파일 sink + 사용자 입력, 함수 내 taint 추적 | 디렉터리 탈출로 임의 파일 접근 위험 |
| SEC-08 | SSRF 찾기 | HTTP client + 사용자 입력, taint 추적 | 서버가 임의 내부 주소로 요청하게 되는 위험 |
| RES-01 | 자원 해제 누락 찾기 | open/malloc/new/acquire와 close/free 짝 | 파일·메모리·핸들 누수 가능성 |
| RES-02 | 무한정 동시성 찾기 | loop 안 goroutine/thread/promise spawn | 폭주, 큐 적체, 장애 증폭 위험 |
| RES-03 | 가변 전역 상태 찾기 | 모듈/package level mutable global | 테스트 격리와 동시성 안정성 저하 |
| HYG-01 | 삼킨 예외·무시된 에러 찾기 | empty catch/except, ignored error | 장애 원인 은폐 위험 |
| HYG-02 | 죽은 코드 찾기 | 미참조 비공개 심볼, 도달 불가 구문 | 유지보수 노이즈와 오래된 경로 |
| HYG-03 | 방치된 TODO/FIXME 찾기 | SATD 주석 개수와 밀도 | 명시된 기술부채 누적 신호 |
| HYG-04 | 매직 리터럴 과다 찾기 | KLOC당 숫자·문자열 리터럴 밀도 | 설명 없는 정책값과 중복 상수 위험 |
| HYG-05 | 주석 밀도 이상치 찾기 | comment/CLOC, 공개 API 문서 누락률 | 문서 부족 또는 주석 과다 신호 |
| HYG-06 | 테스트 부재 신호 찾기 | 테스트 파일 비율, 테스트 없는 디렉터리 | 커버리지는 아니며 test-cli 보강 대상 |
| HYG-07 | 분석 신뢰도를 깨는 파스 실패 찾기 | parser error file:line:column | --strict에서는 exit 3 처리 |
Outputs
사람이 읽는 리포트와 자동화가 읽는 파일을 동시에 만듭니다.
jam-report.md
요약 점수, category score, top findings, grade cap 원인을 리뷰 문서로 남깁니다.
jam-detail.csv
모든 finding을 행 단위로 기록합니다. metric version, threshold, confidence까지 포함합니다.
jam-result.json
대시보드, 회귀 테스트, release gate가 읽기 좋은 구조화 결과입니다.
jam.sarif
GitHub code scanning과 보안 대시보드로 올릴 수 있는 SARIF 2.1.0 출력입니다.
metric_id,severity,confidence,file,line,value,threshold,debt_minutes
CPLX-02,warning,medium,internal/planner.ts,118,21,15,15
DUP-02,warning,medium,service.py,61,0.78,0.72,10
HYG-07,violation,high,parser.go,42,parse_error,0,60JAM Full
jam-full은 test-cli와 security-cli까지 호출하는 프로덕션 게이트입니다.
jam-lite가 정적 코드 건강도를 만들고, test-cli가 테스트/커버리지 증적을, security-cli가 SAST/SCA/secret 증적을 제공합니다. JAM은 세 결과를 하나의 full 점수와 실패 사유로 합성합니다.
일부 컴포넌트만 실행하면 선택된 기본 가중치 합이 1.0이 되도록 재정규화합니다.
jam-lite
jam 단독 실행. 정적 코드 debt, strict 파스 실패, SARIF/CSV/JSON을 담당합니다.
test-cli
pass rate, coverage, evidence strength, density, source mix, skip/duration tail을 test 하위 지표로 분해합니다.
security-cli
severity, policy, category, fixability, CVSS/CWE, suppression, toolchain 상태를 security 하위 지표로 합성합니다.
jam full . --out reports/jam-full
jam full . --component security --out reports/jam-security
jam full . --component test --out reports/jam-testSecurity assurance
Scanner finding과 확정 취약점, 감사 증거를 분리합니다.
중앙 정책과 commit 고정 리뷰 ledger로 보안 후보를 판정하고, framework control plan에 SHA-256 고정 증거를 연결합니다. 결과는 품질 점수와 독립이며 준수 인증을 주장하지 않습니다.
jam assurance verdict --input reports/jam --policy security-policy.json --review security-review.json --gate
jam assurance evidence --plan control-plan.json --out reports/audit --gateE2E evidence
회귀 점수와 독립 보안 라벨을 분리해 검증합니다.
샘플 코퍼스는 고정 SHA를 4개 cache shard에서 실제 clone/scan합니다. jam-lite는 exact score·integrity·provenance와 5종 산출물 계약을 검증합니다. 별도 OWASP validation은 1,001개 지원 사례의 case-level confusion matrix를 고정합니다.
Documentation