Source: docs/10-coverage-and-limitations.md

10. 커버리지와 한계

JAM Lite는 빌드 없이, 오프라인에서, 정적 스캔만으로 동작한다. 이 설계 선택은 명확한 커버리지 경계를 만든다. JAM Full은 JAM Lite 결과에 test-cli와 security-cli 결과를 합성해 테스트/커버리지/보안/SCA 영역을 보완한다. 이 문서는 (1) 표준 품질 모델에 대고 JAM Lite가 어디까지 측정하는지, (2) JAM Full에서 보완되는 영역, (3) 원리적으로 무엇을 측정할 수 없는지를 정리한다.

요약: jam-lite는 유지보수성(구조 품질)에 강하고, 보안은 "명백한 패턴"만, 정확성·성능·런타임 동작은 측정하지 않는다. jam-full은 test-cli/security-cli로 테스트와 보안을 합산하고 v0.2 scanner 실행 coverage를 검증하지만, 그래도 취약점 부재·도메인 정확성·운영 품질·런타임 성능을 증명하지는 않는다.

표준 활용 범위

JAM은 표준의 구조를 측정 계약과 해석 경계에 활용하지만 현재 ISO 적합성 또는 인증을 주장하지 않는다.

ISO/IEC 5055:2021: 자동화된 소스 코드 품질 측정이라는 도구 범위의 가장 가까운 표준 앵커. JAM 메트릭을 해당 개념에 매핑하되 적합성을 선언하지 않음.
ISO/IEC 25020:2019, ISO/IEC/IEEE 15939:2017: 측정 과정, 정보 요구, 결과의 타당성·재현성 관리의 근거. jam-run.json과 불완전 측정 게이트는 이 측정 계약을 기계 판독 가능하게 한다.
ISO/IEC 25023:2016: 제품 품질 특성의 정량 측정 정의와 해석 경계를 제공한다. JAM은 v13에서 production·eligible source 범위를 먼저 명시했고, 제품 profile/integrity tier별 컷은 독립 calibration/validation/holdout 근거가 생긴 뒤 별도 Metrics MAJOR로 도입한다.

1. 소프트웨어 품질 전체에서의 위치 — ISO/IEC 25010 매핑

ISO/IEC 25010:2023 제품 품질 모델의 9개 특성에 대한 JAM의 커버리지다. 2011년 8특성 판의 Usability/Portability 용어를 그대로 쓰지 않고, 2023년 판의 Interaction Capability/Flexibility와 신설 Safety를 반영한다.

품질 특성	커버리지	JAM이 보는 것	JAM이 못 보는 것
유지보수성 (Maintainability)	●●●○ 높음	모듈성(ARCH), 분석가능성(CPLX, SIZE), 수정가능성(DUP, 결합도), 위생/잔재(HYG — 주석코드·미구현 스텁·디버그 잔재·명명 일관성 포함), 재사용성 일부	테스트 용이성의 실측(커버리지), 문서 품질, 도메인 모델 적합성
보안 (Security)	●●○○ 부분	명백한 취약 패턴(시크릿, 인젝션형 결합, 취약 암호, 위험 싱크)	§3 참조 — 인증/인가 설계, 데이터 흐름 추적, 의존성 취약점
신뢰성 (Reliability)	●○○○ 낮음	에러 처리 위생(HYG-01), 자원 누수 패턴(RES) — 신뢰성의 대리 지표만	장애 복구, 가용성, 결함 허용, 실제 에러율
성능 효율 (Performance)	●○○○ 매우 낮음	무한정 동시성(RES-02) 같은 극단 패턴만	알고리즘 복잡도, 메모리 프로파일, 응답 시간, N+1 쿼리
기능 적합성 (Functional Suitability)	○○○○ 없음	—	코드가 요구사항대로 동작하는지는 전혀 모른다. 버그 없는 스파게티도, 우아한 오답도 구분 못 함. jam-full의 opt-in spec 컴포넌트(`--component spec`)는 외부 spec-cli의 요구사항 검증 결과를 합성할 수 있으나, 이는 jam이 기능 적합성을 측정하는 것이 아니라 외부 결과를 그대로 합산하는 것이다(docs/12 §3.2c)
호환성 (Compatibility)	○○○○ 없음	—	API 호환, 상호운용성
상호작용 역량 (Interaction Capability)	○○○○ 없음	—	UX, API 이해가능성, 사용자 오류 방지, 포용성
유연성 (Flexibility)	○○○○ 없음	—	환경 적응성, 확장성, 설치/대체 용이성
안전성 (Safety)	○○○○ 없음	—	인명·재산·환경 위해 회피, fail-safe 설계, 운영 위험 증거

해석: jam-lite 점수는 9개 특성 전체의 "품질 점수"가 아니라 유지보수성 중심 + 보안/신뢰성 일부 대리 신호다. jam-full은 테스트/커버리지와 보안/SCA를 더하지만, "JAM A등급 = 출시 가능"은 아니다. JAM은 ISO/IEC 25010 특성에 자체 지표를 매핑할 뿐, ISO 적합성 인증을 주장하지 않는다.

1.1 점수 모집단과 coverage 한계

metrics v13은 전체 repository를 곧바로 제품 코드로 간주하지 않는다. test/documentation/configuration/generated는 finding을 보존하되 product score에서 제외하고, 카테고리별 구현 언어만 eligible CLOC로 사용한다. jam-run.json의 roles와 categoryCoverage, jam-result.json의 category coverage가 이 경계를 공개한다. coverage가 낮은 카테고리의 높은 점수는 “전체 저장소가 우수함”이 아니라 측정 가능한 production 부분에서 관찰된 debt가 낮음을 뜻한다. 전 카테고리가 미측정이면 N/A다.

2. 아키텍처 커버리지

2.1 보는 것 — 정적 모듈 구조 (module viewtype)

소프트웨어 아키텍처 문헌(Clements et al., *Documenting Software Architectures*)은 아키텍처 뷰를 크게 모듈 뷰 / 컴포넌트-커넥터(런타임) 뷰 / 할당(배포) 뷰로 나눈다. JAM은 이 중 모듈 뷰만 본다.

아키텍처 관심사	커버	메트릭
모듈 분해와 크기 균형	✓	SIZE-01/04, ARCH-04
의존 방향과 순환	✓	ARCH-01/02
결합도/안정성	✓	ARCH-03 (Ca/Ce/I, SDP)
응집도	△ 부분	ARCH-07 LCOM4(Go/TypeScript), SIZE-04 God Type(Go AST + 임베드 tree-sitter WASM 지원 언어). 타입 해석 없는 언어/동적 디스패치는 미커버
레이어 규칙 위반 (예: domain→infra 금지)	✓ (opt-in)	사용자가 jam.yaml `arch.layers`/`arch.rules`(deny) 선언 시 ARCH-09로 검사 — 선언 없으면 미측정(기존 프로젝트 점수 불변)

2.2 못 보는 것 — 런타임/배포/의도

영역	왜 못 보는가
런타임 토폴로지	프로세스/스레드 구조, 서비스 간 통신(HTTP/큐/RPC), 이벤트 흐름은 실행해야 보인다. 마이크로서비스 간 순환 호출은 import 그래프에 안 나타남
데이터 아키텍처	스키마 설계, 트랜잭션 경계, 일관성 모델
배포/인프라	스케일링, 장애 격리, IaC 품질 (Dockerfile/Terraform은 v1 분석 대상 아님)
설계 의도와 도메인 적합성	"이 분해가 비즈니스 도메인에 맞는가"는 정량화 불가. 순환이 없어도 잘못된 경계일 수 있음
숨은 결합	DB 테이블 공유, 환경변수, 전역 설정, 문자열 키를 통한 암묵 결합은 import 그래프에 없다

2.3 정밀도 한계 (보이는 영역 안에서도)

import 해석은 휴리스틱: 빌드 없이 경로/메타파일 기반 해석(05-language-support.md §2.2). 동적 import(importlib, require(변수)), 모노레포 특수 alias, 코드 생성 후 참조는 놓친다. → 설계상 미탐(누락) 쪽으로 보수적 — 가짜 순환을 만드는 것보다 낫다는 선택.
타입 해석 없음: 인터페이스 구현 관계, 동적 디스패치, DI 컨테이너 와이어링을 못 따라간다. "구현체가 어디서 쓰이나"류 분석 불가 → 죽은 코드(HYG-02)도 비공개 심볼만 보수적으로 판정.

3. 보안 커버리지 — OWASP Top 10 / CWE 매핑

JAM의 SEC 메트릭은 로컬 패턴 매칭(함수 내 추적까지만)이다. 함수 경계·파일 경계를 넘는 taint 분석을 하지 않으므로, "소스에서 싱크까지 흐르는" 취약점의 대부분을 원리적으로 놓친다.

OWASP Top 10 (2021) 기준

OWASP	항목	커버	비고
A01	Broken Access Control	✗	인가 로직의 의미를 이해해야 함 — 정적 패턴으로 불가
A02	Cryptographic Failures	△	SEC-01(시크릿), SEC-03(취약 해시/TLS) — 명백한 경우만. "암호화해야 할 데이터를 안 한 것"은 못 봄
A03	Injection	△	SEC-02 — 같은 함수 안의 직접 결합만. 계층을 거쳐 흐르는 인젝션은 미탐
A04	Insecure Design	✗	설계 리뷰의 영역
A05	Security Misconfiguration	△	TLS 검증 해제 등 코드 내 설정만. 인프라/서버 설정 파일은 범위 밖
A06	Vulnerable Components	✗	SCA 아님 — 의존성 CVE 대조는 취약점 DB가 필요하고 오프라인 제약과 충돌. lock 파일은 읽지만 CVE 매칭 안 함
A07	Auth Failures	✗	세션/인증 흐름의 의미 분석 필요
A08	Software/Data Integrity	△	SEC-04(위험 역직렬화)만
A09	Logging Failures	△	SEC-05(민감정보 로깅)만 — "로깅이 부족한 것"은 못 봄
A10	SSRF	△	SEC-08 — JS/TS의 직접 입력 토큰과 함수 내 taint만. 함수/파일 경계 흐름은 미탐

정직한 요약: OWASP 10개 중 부분 커버 6개, 완전 미커버 4개. CWE Top 25 기준으로도 메모리 안전(CWE-787/125 등) 계열은 동적/심볼릭 분석 영역이라 미커버이고, JAM이 직접 잡는 것은 CWE-798(시크릿), CWE-89/78(직접 결합형), CWE-327/338/295(암호/TLS), CWE-502(역직렬화), CWE-532(로깅), CWE-79/22/918의 제한된 JS/TS 흐름 정도다.

검출 특성

정밀도(precision) 우선은 설계 목표이지 전 언어에서 입증된 결과가 아니다: confidence 체계와 보수적 판정이 있어도 Java SEC-02의 OWASP 독립 라벨 기준선은 CWE-78/89 FPR이 약 88%였고, SEC-03의 해당 CWE-327 recall은 0%였다(16-independent-security-validation.md). 따라서 "SEC 점수 100 = 보안 양호"도, 낮은 점수의 모든 finding이 실제 취약점이라는 해석도 금지한다. 언어·CWE별 검증값과 finding 근거를 함께 봐야 한다.
git 히스토리 스캔 안 함: 시크릿이 과거 커밋에 남아 있어도 현재 트리에 없으면 못 본다 (gitleaks/truffleHog의 히스토리 모드와 다름).
jam-full security 0건의 의미: security-cli v0.2의 모든 requested scanner가 success 또는 not_applicable이고 coverage가 complete라는 실행 증적까지 확인했다는 뜻이지, 미탐이 없거나 규제 적합성이 증명됐다는 뜻은 아니다. coverage가 불완전하면 JAM은 clean/low score를 만들지 않고 coverage_incomplete 측정 오류로 실패한다.

4. 원리적 한계 — 왜 "완벽한 정적 분석"은 없는가

Rice의 정리: 프로그램의 의미적(semantic) 속성 판정은 일반적으로 결정 불가능. 모든 정적 분석은 근사이며, 오탐(false positive)과 미탐(false negative) 사이의 트레이드오프를 강제당한다. JAM은 진단 도구로서의 신뢰 유지를 위해 오탐 최소화 쪽을 선택했다 → 미탐을 감수한다.
빌드 부재의 비용: 타입 정보, 심볼 해석, 매크로/제네릭 전개가 없다. 컴파일러 기반 도구(CodeQL, go vet)보다 의미 이해가 한 단계 얕은 것은 *설계 비용*이지 버그가 아니다. 그 대가로 어떤 환경에서든(의존성 깨진 프로젝트 포함) 돌아간다 — 바이브코딩 산출물은 빌드조차 안 되는 경우가 많다는 점에서 이 트레이드는 의도적이다.
메트릭의 대리성: 모든 메트릭은 품질의 *대리 지표(proxy)*다. CCN이 낮다고 이해하기 쉬운 코드가 아니고(잘게 쪼갠 스파게티 가능), 중복이 없다고 추상화가 옳은 것도 아니다(잘못된 DRY). Goodhart의 법칙 — "지표가 목표가 되면 좋은 지표이기를 멈춘다" — 는 JAM 점수에도 적용된다. 점수 올리기용 기계적 분할은 점수는 올리지만 품질은 올리지 않는다.
임계값의 자의성: 문헌 기반이라 해도 임계값(CCN 10/15 등)은 모집단 평균에서 온 관례이지 물리 법칙이 아니다. 도메인(예: 파서, 상태머신)에 따라 정당하게 복잡한 코드가 있다 → suppress 메커니즘(07-cli-and-config.md)이 일급 기능인 이유.

5. JAM이 아닌 것 (Not-a-list)

jam-lite는 ~이 아니다	jam-full 보완
의존성 취약점 스캐너(SCA)	security-cli(Trivy/OSV/Grype 등)
정밀 SAST (taint/데이터 흐름)	security-cli의 Semgrep profile 또는 전문 도구
시크릿 히스토리 스캐너	security-cli의 gitleaks profile
테스트/커버리지 도구	test-cli
린터/포매터 (lite 코어)	ESLint, ruff, golangci-lint — 단, jam-full의 opt-in lint 컴포넌트(`--component lint`)가 로컬 린터를 오프라인·설정격리·프로버넌스 각인 방식으로 합성한다(현재 ruff; docs/12 §3.2b)
라이선스 컴플라이언스	security-cli license profile
요구사항 검증 도구	spec-cli 계약(외부) — jam-full의 opt-in spec 컴포넌트(`--component spec`)가 verified/failed/unverified 결과만 합성(docs/12 §3.2c)
동적 분석/프로파일러	sanitizers, fuzzer, APM
사람의 설계 리뷰	대체 불가 — JAM은 리뷰어가 어디부터 볼지를 알려주는 도구

6. 종합 커버리지 맵

                         ◄─── jam-lite 커버리지 ───►
 구조 품질   ████████████████████░░░░░  높음   (모듈 뷰 한정. 런타임/도메인 적합성 제외)
 코드 품질   ███████████████░░░░░░░░░░  중상   (복잡도·중복·위생. 정확성 제외)
 보안        ███████░░░░░░░░░░░░░░░░░░  부분   (명백한 패턴만. OWASP 5/10 부분, taint 없음)
 신뢰성      ████░░░░░░░░░░░░░░░░░░░░░  낮음   (에러 처리 위생 = 대리 지표)
 성능        ██░░░░░░░░░░░░░░░░░░░░░░░  매우 낮음
 정확성      ░░░░░░░░░░░░░░░░░░░░░░░░░  없음   (요구사항 충족 여부는 측정 불가)

사용자에게 전달할 한 문장

jam-lite 점수는 "이 코드가 옳은가"가 아니라 "이 코드 위에 계속 쌓아도 되는가"에 대한 답이고, jam-full 점수는 테스트/보안 도구 결과를 더한 품질 게이트다. 둘 다 출시 증명서는 아니다.

7. 제품 반영 사항

이 한계 인식을 문서에만 두지 않고 도구 동작에 반영한다:

리포트 머리말에 범위 고지: jam-report.md 상단에 jam-lite 범위를 고정 출력하고, jam-full은 test/security 컴포넌트와 합산임을 별도 리포트에 기록한다.
SEC 카테고리 명명: 리포트에서 "Security"가 아니라 "Security (patterns)" 로 표기해 SAST 대체로 오인되지 않게 한다. 같은 원칙으로 spec 컴포넌트는 "Functional"이 아니라 "Functional (external)"로 명명해, jam이 기능 적합성을 직접 측정한 것으로 오인되지 않게 한다.
jam explain --limits: 각 메트릭의 미탐 유형을 CLI에서 조회 가능하게 한다 (예: ARCH-01: 동적 import는 추적하지 않음).
confidence 노출: 휴리스틱 finding의 확신도를 숨기지 않는다 (03-scoring-model.md §4).
커버리지 매트릭스 버전 관리: 메트릭이 추가될 때마다 이 문서의 §1/§3 표를 갱신한다 — 커버리지 주장의 근거가 항상 현행이어야 한다.