Home/Reference/08. 구현 로드맵

Reference

08. 구현 로드맵

마일스톤, 단계별 산출물, 검증 전략

Source: docs/08-roadmap.md

08. 구현 로드맵

현재 기준(v0.40.0 / metrics v14.0.0): 기본 제품 경로는 jam-lite(정적 코드 건강도), jam-full(외부 컴포넌트 합성 점수), 점수와 독립된 jam assurance(취약점 판정·감사 증거)다. 런 provenance·완전성·production/eligible score scope, companion CLI v0.2 계약, 명시적 decision-grade 상태, OWASP Java 독립 라벨 기준선, commit 고정 security review/control evidence 계약을 완료했다. 다음 최우선은 companion dependency scope/VEX와 재현 가능한 test environment 계약을 추가하고, Java SEC 정밀도·NIST/실제 프로젝트 holdout을 교차 검증하는 것이다.

마일스톤 개요

마일스톤산출물완료 기준
M0 골격CLI + 파이프라인 + 출력 뼈대jam scan이 빈 finding으로 report/csv 생성
M1 Go 수직 슬라이스Go 언어 전체 메트릭Go 픽스처에서 모든 카테고리 검출
M2 tree-sitter 통합TS/JS, Python 지원3개 언어 동일 메트릭 동작
M3 점수·리포트 완성점수 모델 + 캘리브레이션양성/음성 대조군 통과
M4 v1.0 릴리스3-OS 바이너리, 문서goreleaser 매트릭스 빌드
M5+ 확장Java/C#/Rust, C/C++(제한), diff, SARIF—

M0 — 골격 (작업 1주 규모)

  1. cmd/jam + cobra(또는 stdlib flag) CLI, scan/version 서브커맨드.
  2. internal/discover: 파일 순회, .gitignore 파싱, 언어 감지, 생성 파일 휴리스틱. 결정적 정렬 포함.
  3. internal/model: Finding/Location/Severity 등 공용 타입 확정 (04-architecture.md §3).
  4. internal/report: 빈 데이터로도 동작하는 markdown/csv writer + golden 테스트.
  5. CI: 3-OS 매트릭스에서 go test, CGO_ENABLED=0 빌드 확인.

의도: 출력 스키마와 파이프라인 계약을 먼저 동결 → 이후 analyzer는 병렬 개발 가능.

M1 — Go 수직 슬라이스 (2주 규모)

go/ast 기반으로 모든 메트릭을 한 언어에서 끝까지 구현한다. tree-sitter 추상화를 설계하기 전에 메트릭 로직의 실제 요구사항을 파악하는 것이 목적(추상화를 두 번째 사례 전에 만들지 않는다).

  1. SIZE-01~04, CPLX-01~05 (go/ast 노드 워커).
  2. ARCH-01/03: go.mod 파싱 → import 그래프 → Tarjan SCC. 사이클 경로 복원 포함.
  3. DUP-01: go/scanner 토큰 → 정규화 → Rabin-Karp 인덱스. (이 모듈은 처음부터 언어 중립 토큰 인터페이스로 작성 — M2에서 재사용)
  4. SEC-01(엔트로피+정규식 — 언어 무관 모듈), SEC-02~05 Go 패턴, RES-01~03 Go 룰, HYG-01~06.
  5. internal/score: SQALE debt → 카테고리 점수 → 등급, cap·confidence 규칙.
  6. 픽스처: testdata/fixtures/go-bad/(전 카테고리 안티패턴 주입), go-good/(모범 코드). 각 메트릭당 최소 1 검출 + 0 오탐 어서션.

M2 — tree-sitter 통합 (2~3주 규모)

상태 (v0.2): tree-sitter WASM은 emscripten 툴체인 부재로 이연 — 리스크 레지스터의 폴백 경로(자체 경량 렉서)를 채택해 TS/JS·Python 프론트엔드(internal/lang/jsts, internal/lang/python)로 SIZE-02/03, CPLX-01~03, ARCH-01/03을 confidence=medium으로 지원한다(ts-bad/, py-bad/ 픽스처 포함). tsconfig paths/alias는 미구현.

재검증 (2026-06-14, ARCH-07 LCOM4 후속): 동기 — ARCH-01~06이 import 그래프 한 관점만 보므로, 타입 내부 구조(응집도 LCOM·추상도·상속)를 *전 언어*로 보려면 실제 AST가 필요하고 그 길은 tree-sitter다(ARCH-07은 go/ast로 Go에서 먼저 증명). 확인된 사실:

  • 런타임 OK: wazero(순수 Go WASM 런타임, 유일 의존 golang.org/x/sys)는 받아져 동작하며 CGO_ENABLED=0 정적 빌드를 유지한다 → 런타임 쪽은 해결됨.
  • 바인딩이 진짜 작업: tree-sitter 공식 Go 바인딩은 CGo라 정적 릴리스를 깬다. 순수 Go·wazero용 턴키 바인딩은 없다. web-tree-sitter용 문법 wasm은 emscripten ABI라 JS 글루가 필요.
  • 권장 아키텍처 (emscripten 회피): tree-sitter 런타임+문법을 묶은 작은 C/Rust 래퍼를 wasm32-wasi로 컴파일해 "소스 바이트 → 직렬화 파스트리(노드 타입·범위)"를 노출하고, wazero의 네이티브 WASI로 구동한다. emscripten JS ABI 불필요, 순수 Go·정적 바이너리 유지.
  • 이 환경의 차단점(확정): wasm 빌드 툴체인 부재 — clang/wasi-sdk/rust(wasm32-wasi)/tinygo/emscripten 모두 없음. 따라서 *문법 wasm 아티팩트를 만들 수 없어* M2 빌드는 wasm32-wasi 툴체인(예: wasi-sdk 또는 rustup +wasm32-wasi) 1회 프로비저닝이 선결이다. 그 후엔 위 아키텍처로 다언어 ARCH-07/추상도/상속 확장.
  • 막히지 않은 선행 작업: §2의 공통 AST 인터페이스(go/ast 어댑터가 지금 구현, tree-sitter 어댑터가 후속) 추출은 툴체인 없이 가능 — 토큰체인 확보 시 백엔드만 끼우면 되도록.
  1. wazero 래퍼: wasm 로드, 파서 풀, 쿼리 실행, 에러 노드 처리. 문법 wasm 빌드 스크립트와 아티팩트 캐시. (WASI 인터페이스 권장 — emscripten ABI 대신.)
  2. 공통 AST 인터페이스 추출: M1의 go/ast 어댑터와 tree-sitter 어댑터가 같은 인터페이스 구현. 타입 구조(타입·메서드 소속·필드·상속)를 포함해 ARCH-07(LCOM4)·추상도·DIT를 전 언어로 확장 가능하게. (툴체인 무관, 선행 가능.)
  3. lang.Spec 데이터 구조 확정, TypeScript/JavaScript → Python 순으로 작성.
  4. import 해석기: tsconfig paths, package.json, Python 패키지 규칙 (05-language-support.md §2.2).
  5. 성능 측정: 100k LOC 벤치마크 리포지토리로 30초 목표 검증. 미달 시 폴백 계획 발동.
  6. 픽스처를 언어별로 복제(ts-bad/, py-bad/ ...).

M3 — 점수 캘리브레이션과 리포트 품질 (1~2주 규모)

  1. 양성 대조군: 잘 관리되는 OSS 5개+ 스캔 → B 이상 확인, 오탐 원인 분석·수정.
  2. 음성 대조군: 실제 바이브코딩 산출물 수 개 → D 이하 확인, 미탐 보완.
  3. 임계값/가중치 조정 결과를 docs/calibration.md로 기록(데이터 근거 남김).
  4. 리포트 가독성 다듬기: Top Findings 선정 로직, 한국어/영어 메시지 카탈로그.
  5. suppress/inline-ignore, --fail-under, --only 등 운영 기능 마감.

M4 — v1.0 릴리스 (1주 규모)

  1. goreleaser: windows/linux/darwin × amd64/arm64, 체크섬, 단일 정적 바이너리 검증.
  2. Windows 실환경 검증: CRLF, 경로, 콘솔 색상.
  3. 사용자 문서: README 갱신, jam explain 콘텐츠, 예제 리포트.
  4. 라이선스 점검: tree-sitter 문법별 라이선스(MIT 대부분) 고지 파일.

M5+ — 확장 (우선순위 순)

  1. v0.4 (완료): Java, C#, Rust 지원 — 정식 지원 6개 언어 완성. Rust는 unsafe/unwrap 등 고유 룰 포함(05-language-support.md §2.4). metrics spec v1.2.0.
  2. v0.5 (완료): jam diff old.csv new.csv — finding_id 기반 added/fixed/unchanged 비교와 --fail-on-added CI 게이트.
  3. v0.6 / metrics v2.0.0 (완료): SARIF 출력(--sarif), 파스 실패 HYG-07, --strict, 설정 기반 메트릭 임계값 오버라이드.
  4. v0.7 / metrics v2.1.0 (완료): C/C++ 제한 지원 — 전처리기 미전개의 한계 안에서 SIZE/CPLX/ARCH include 그래프/DUP/SEC-01/HYG/RES-01 중심 (05-language-support.md §5).
  5. v0.8 (완료): jam-lite/jam-full 분리, test-cli/security-cli 외부 컴포넌트 호출, full 합성 리포트.
  6. v0.9 / metrics v2.2.0 (완료): HYG-04 매직 리터럴 밀도, HYG-05 주석 밀도 이상치 구현.
  7. v0.10 / metrics v2.3.0 (완료): CPLX-04/05, ARCH-02, DUP-02 구현 — jam-lite registry 메트릭 전부 활성화.
  8. v0.10.1 / metrics v2.3.1 (완료): 실제 저장소 캘리브레이션 — SEC false positive 완화, DUP-02 최소 크기 상향, 공통 테스트 경로 분류.
  9. v0.10.2 / metrics v2.3.2 (완료): DUP-01 캘리브레이션 — 테스트 파일 제외, 최소 6라인 조건, DUP 대상 CLOC 기준 중복률.
  10. v0.10.3 / metrics v2.3.3 (완료): HYG-04 캘리브레이션 — config 파일과 자연어 copy 문자열 제외.
  11. v0.10.4 / metrics v2.3.4 (완료): Rust ARCH-01/03 캘리브레이션 — mod.rs facade/re-export 부모·자식 모듈 계층 엣지 제외, sibling cycle 검출 유지.
  12. v0.10.4 E2E 기준선 (완료): 지원 언어별 best/stress 샘플 코퍼스 clone·스캔, 13-e2e-sample-evaluation.md와 testdata/e2e-corpus.yaml에 결과와 jam-full 보완 필요 영역 기록.
  13. v0.10.5 full E2E (완료): test-cli/security-cli를 실제 연결해 16개 샘플 full 스캔, 보안 보완 효과와 test runner/toolchain 부족을 14-jam-full-e2e-evaluation.md에 기록. policy-pass medium/low-only security score 하한 보정.
  14. v0.10.6 full E2E toolchain 보강 (완료): Python/Java/.NET/Rust/Node runner toolchain을 설치해 16개 샘플 full 재측정. test-cli의 "no test results or coverage were produced"는 infrastructure error가 아니라 test quality failure로 분류해 exit 1로 게이트.
  15. v0.10.7 full 부분 실행 (완료): --component test|security|all, --skip-test, --skip-security로 부분 full 실행 지원. 선택 컴포넌트 기준 effective weight 재정규화와 reason 필드로 실패 원인 구조화.
  16. v0.13.0 / metrics v4.0.0 (완료): TDRMax를 0.20에서 0.10으로 낮춰 대형 프로젝트에서 debt가 과도하게 희석되는 문제를 보정.
  17. v0.14.0 / metrics v5.0.0 (완료): SEC-02 SQL/명령 인젝션을 critical로 에스컬레이션하고 Java/C# 탐지를 추가해 취약 앱이 A/B로 남는 문제를 제거.
  18. v0.15.0 (완료): 루트와 하위 .gitignore를 모두 적용하고 node_modules, .venv, venv, .next, target, dist, lockfile 등 dependency/build/generated 산출물을 기본 스캔에서 제외.
  19. v0.16.0 / metrics v6.0.0 (완료): SEC-04 위험 역직렬화/동적 실행을 싱크 인자가 비리터럴(eval(req.body.x) 등)일 때 critical로 에스컬레이션해, SSJI 취약 앱(NodeGoat 류)이 A로 남던 마지막 jam-lite 보안 미탐지 공백을 제거.
  20. v0.17.0 / metrics v6.1.0 (완료): ARCH-05 Hub-Like Dependency와 ARCH-06 Propagation Cost를 추가해 순환이 없어도 fan-in/fan-out 과결합과 변경 전파 위험을 찾는다.
  21. v0.18.0 / metrics v7.0.0 (완료): SEC worst-case 카테고리 상한과 등급 캡 총점 클램프, release metadata 자동 검사.
  22. v0.22~0.29 / metrics v8.x (완료): wazero+wasm32-wasi tree-sitter 경로, 다언어 god type/DIT/LCOM4/함수 내 taint.
  23. v0.37.0 / metrics v12.3.0 (완료): jam-run.json 런 매니페스트, policy/config/scope hash, 불완전 측정 표시와 strict gate, 호환성 검증 diff, 라인 이동 안정 finding ID, 구조화된 억제 lifecycle.
  24. v0.38.0 / metrics v13.0.0 (완료): production/test/docs/config/generated 역할 분리, 카테고리×언어별 eligible production CLOC 분모와 coverage, 미측정 N/A, 명시적 score_exclusion, 근거 없는 단일 파일 30% debt 할인 제거, result v3/manifest v2.
  25. 프로필 메타데이터·pinned E2E CI (완료): 기존 16종을 profile·partition=regression·expected_integrity로 명시하고, tools/e2e-corpus와 4-shard cache workflow가 실제 clone/고정 SHA checkout/strict scan/exact score·grade·integrity/Git provenance/JSON·CSV·SARIF·Markdown 계약을 검증한다. jam/e2e-summary@1 층화 결과를 CI artifact로 남긴다.
  26. 독립 보안 라벨 타당화 1차 (완료): OWASP BenchmarkJava commit과 expectedresults SHA-256, CWE-78/89/327→SEC-02/03 매핑을 결과 관측 전에 고정했다. tools/labeled-benchmark가 1,001개 지원 사례의 case-level TP/FN/TN/FP와 precision/recall/FPR/F1, Git/integrity/산출물 계약을 검증한다. metrics v13 aggregate baseline은 TP 354/FN 174/TN 157/FP 316, precision 52.84%, recall 67.05%, FPR 66.81%, F1 59.10%이며 16-independent-security-validation.md에 한계와 결정을 기록했다.
  27. v0.39.0 보안 판정·감사 증거 (완료): jam assurance verdict가 JAM/security-cli 후보를 Git commit·target·시간·coverage/toolchain과 결합하고, reviewer ledger의 confirmed/false-positive/accepted-risk/fixed/verified 상태와 중앙 정책을 게이트한다. jam assurance evidence는 framework control plan과 원본 증거 SHA-256, source hash, 예외 만료를 연결하되 complianceClaim=false를 고정한다.
  28. v0.40.0 / metrics v14.0.0 companion v0.2 계약 통합 (완료): test-cli report@2 canonical quality cap과 baseline/history/diff 전달, security-cli scanner coverage fail-closed gate와 baseline 전달, spec-cli trace/summary binary gate와 세 원본 artifact를 표준화했다. 공개 test-cli v0.3.0, security-cli v0.3.0, spec-cli v0.2.0 바이너리로 실제 실행 호환성을 검증했다.
  29. v0.40.0 full 측정 신뢰성 보강 (완료): jam-full schema v2의 decision=pass|fail|incomplete, final/provisional·usable 계약, jam-lite integrity 전파, 실재 artifact만 기록, test-cli v0.3.0의 Rust nextest JUnit 격리 설정·Python pytest 파일 감지 정밀화, security-cli v0.3.0의 Gitleaks working-tree 기본/명시적 history 모드와 범위 증적을 추가했다. 16종 재검증에서 decision-grade 5→7, Rust report 0→2, .git 보존 코퍼스 Gitleaks 합계 2,547초(13개)→5.7초(16개)를 확인했다.
  30. companion 범위·환경 계약 (다음): SCA finding에 runtime/development/build/test scope와 VEX 상태를 보존하고 조직 정책이 scope별 gate를 선언하게 한다. test-cli는 dependency bootstrap을 암묵 수행하지 않되 runner/toolchain/project dependency 준비 상태를 report 계약으로 분리해, 테스트 실패와 환경 미준비를 JAM이 fail/incomplete로 구분하게 한다.
  31. 독립 외적 타당화 2차 (다음): Java SEC-02 source-to-sink/sanitizer 구분과 SEC-03 cipher 범위를 근거 기반으로 개선하되 동일 OWASP confusion matrix에서 TP 증가와 FP 비증가를 함께 게이트한다. 이어 NIST Juliet adapter와 app/library/CLI/embedded/monorepo별 calibration/validation/holdout 저장소를 기존 regression corpus와 분리해 FP/KLOC·순위 안정성을 검증한다. 이 근거가 생긴 뒤에만 가중치/컷/cap을 바꾸는 Metrics MAJOR를 검토한다.
  32. --lsp 정밀 모드, 사용자 정의 룰(YAML+tree-sitter 쿼리) 플러그인, HTML 로컬 뷰어(jam serve).

리스크 레지스터

리스크영향완화
wazero 경유 tree-sitter 성능 미달스캔 시간 초과M2 §5에서 조기 벤치마크. 폴백: 자체 렉서 분리 + CGo 빌드 태그 옵션
import 해석 오탐 → 가짜 순환신뢰 훼손 (가장 치명적)해석 실패는 외부 처리(보수적). 양성 대조군에서 가짜 사이클 0건을 릴리스 게이트로
SEC 휴리스틱 오탐 과다점수 무의미화confidence 체계 + 억제 메커니즘 + 대조군 캘리브레이션
문법 wasm 임베드로 바이너리 비대배포 불편언어당 ~3MB 수준 — 지원 7개 문법(6개 언어 + C/C++) 전부 내장해도 수십 MB로 허용 범위. 초과 시 언어별 빌드 태그 분리
임계값에 대한 사용자 반발도입 저항모든 임계값 문헌 근거 명시(jam explain) + 전부 설정 가능

테스트 전략 요약