feat(kebab-parse-image): P6-1 image extractor + EXIF whitelist #32
Reference in New Issue
Block a user
Delete Branch "feat/p6-1-image-extractor-exif"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
요약
P6-1 —
kebab-parse-imagecrate 신설.MediaType::Image(_)자산을 단일 블록CanonicalDocument로 변환하는ImageExtractor구현. parser_version"image-meta-v1".contract:
docs/superpowers/specs/2026-04-27-kebab-final-form-design.md§3.4 (Block::ImageRef + ImageRefBlock), §3.7a (OcrText / ModelCaption stubs), §9.1 (image extraction policy), §9 (versioning).동작 계약
Block::ImageRef정확히 1건. OCR / caption 필드는 None — P6-2 / P6-3 에서 채운다.metadata.user["exif"]— 화이트리스트 태그만:Make,Model,Software,DateTimeOriginal(ISO-8601 변환),Orientationgps_lat,gps_lon(DMS triple + N/S/E/W ref → signed decimal degree)metadata.user["dimensions"]—{w, h, format}(lowercase:png/jpeg/webp/gif/tiff/other).SourceSpan::Region { 0, 0, w, h }이 전체 이미지 영역.metadata.source_type = Reference,trust_level = Primary,lang = "und".doc_id+block_id(§4.2 ID recipe 그대로).Discovered,Parsed. 손상 입력일 때Warning추가.실패 모드
{}null+ Warning + span(0,0,0,0)(Err 아님)null+ Warninganyhow::Error(caller skip)의존성 경계 (§8)
kebab-core만, image (default features off,png/jpeg/webp/gif/tiff만), kamadak-exif 0.6, anyhow / serde / serde_json / time / tracing / thiserror.kebab-source-fs,kebab-parse-md,kebab-normalize,kebab-chunk,kebab-store-*,kebab-embed*,kebab-search,kebab-llm*,kebab-rag, UI crate 모두 미참조 (forbidden 침범 없음).테스트
cargo test -p kebab-parse-image— 14건 (4 unit + 10 integration) 통과:Errsupports()매칭, media_type 불일치 거부Writer로 EXIF blob 만든 뒤 SOI 직후 APP1 splice) — 바이너리 fixture 커밋 없음.Test plan
🤖 Generated with Claude Code
- 새 crate kebab-parse-image 추가 (workspace 19개째). MediaType::Image(_) 자산을 단일-블록 CanonicalDocument 로 변환하는 ImageExtractor 구현. - parser_version "image-meta-v1" (§9 versioning). - 본문은 Block::ImageRef 1건만 포함 — OCR / caption 필드는 None 으로 남겨 두고 P6-2 / P6-3 에서 채운다. - EXIF 화이트리스트 (§9.1, PII 표면 최소화): Make / Model / Software / DateTimeOriginal / Orientation / GPSLatitude(+Ref) / GPSLongitude(+Ref). MakerNote / Thumbnail / 기타 태그는 폐기. DateTime 은 EXIF "YYYY:MM:DD HH:MM:SS" → ISO-8601 변환. GPS DMS triple + N/S/E/W ref → signed decimal degree. - 차원: image::ImageReader 헤더만 읽어 (w, h, format) 획득. 16k×16k cap 초과 또는 디코드 실패 → metadata.user.dimensions = null + Provenance Warning 이벤트 (Err 아님). 포맷 자체 인식 실패 → anyhow::Error (caller skip). - SourceSpan::Region { 0, 0, w, h } 으로 전체 이미지 영역 표기. 결정성: 동일 bytes + 동일 parser_version → 동일 doc_id + block_id (§4.2 ID recipe 그대로 사용). - metadata.source_type = Reference, trust_level = Primary, lang = "und". title = 확장자 제외 파일명, alt = 파일명. - 의존성 경계 (§8): kebab-core 만 + image 0.25 (default features off, png/jpeg/webp/gif/tiff 만), kamadak-exif 0.6, anyhow / serde / serde_json / time / tracing / thiserror. kebab-source-fs · parse-md · store-* · embed* · llm* · rag · UI crate 미참조. - 테스트 14개 (4 unit + 10 integration): • PNG 차원 추출, JPEG EXIF GPS 추출 (DMS → decimal 변환 정확도 1e-6), EXIF 없는 PNG → 빈 map, 손상 PNG → warning + null dims (panic 없음), 인식 불가 bytes → Err, 결정성, 스냅샷, supports() 매칭, media_type 불일치 거부. • 픽스처는 in-memory 생성 (PNG 는 image crate, EXIF JPEG 는 kamadak Writer 로 EXIF blob 만든 뒤 SOI 직후 APP1 splice) — 바이너리 fixture 커밋 없음. - HEIC / RAW 는 spec 상 v1 out of scope (image crate 미지원, Apple Vision sidecar 가 추후 P+ 에서 채움). - tasks/p6/p6-1-image-extractor-exif.md status: planned → completed. contract: docs/superpowers/specs/2026-04-27-kebab-final-form-design.md sections: §3.4 Block::ImageRef + ImageRefBlock, §3.7a OcrText / ModelCaption stubs, §9.1 image extraction policy, §9 versioning.회차 1 — 큰 그림은 견고합니다. 결정성 ID 계산, 16k×16k cap, EXIF 화이트리스트, 손상 입력의 warning 폴백, 픽스처 in-memory 생성 (특히 kamadak
Writer+ APP1 splice 조합) 모두 spec 의 요구를 정확히 짚었고, integration 테스트가 동작 contract 의 핵심 분기 (정상 / EXIF 없음 / 손상 / 인식 불가 / media_type 불일치 / 결정성 / 스냅샷) 를 빠짐없이 커버합니다.다만 머지 전에 정리해 두면 좋을 actionable 한 지적이 몇 건 있어 REQUEST_CHANGES 로 둡니다:
Cargo.toml— 미사용 deps (serde,thiserror) 와serde_json의 dev-deps 중복 (3건).lib.rs— 변수명decode_warning이 cap 초과 분기까지 포함하면서 의미가 어긋남.exif_extract.rs—In::PRIMARY만 받는 dead-flexibility 인자 1건, 두 단if let의 let-chain 정리 1건, EXIF 키 네이밍 컨벤션 (PascalCase vs snake_case) 통일 1건.tests/common/mod.rs— 호출되지 않는fake_path헬퍼 +Pathimport.칭찬도 한 줄 —
tests/extractor.rs의 EXIF 화이트리스트 누수 검증 (allowed HashSet 와for k in exif.keys()의 조합) 은 P6-2 / P6-3 가 새 키를 추가할 때도 같은 패턴을 재사용할 수 있는 좋은 단서가 됩니다.@@ -0,0 +9,4 @@[dependencies]kebab-core = { path = "../kebab-core" }anyhow = { workspace = true }serde가[dependencies]에 들어 있는데 crate 내부 어느 파일에도use serde::/#[derive(Serialize)]같은 직접 사용처가 없습니다. 직렬화는kebab-core가 재내보내는 타입의 derive 만으로 충분하므로 직접 의존성에서 제거해 주세요. 의존성 경계 (§8) 가 빡빡한 워크스페이스라cargo tree출력에 불필요한 라인이 늘어나는 것도 피하면 좋습니다.@@ -0,0 +13,4 @@serde = { workspace = true }serde_json = { workspace = true }time = { workspace = true }tracing = { workspace = true }thiserror도 같은 맥락으로 미사용입니다. crate 내부에 별도 도메인 에러 enum 이 없고 모든 실패 경로는anyhow::Error로 흘려보내고 있어서, 지금은 dead dep 입니다. 추후 명시적ExtractErrorenum 을 도입하는 패치에서 다시 추가하는 편이 깔끔합니다.@@ -0,0 +26,4 @@[dev-dependencies]tempfile = { workspace = true }blake3 = { workspace = true }serde_json이 이미[dependencies]에 선언되어 있어[dev-dependencies]재선언은 중복입니다. dev 빌드도 deps 항목을 그대로 사용하므로 이 줄을 지워도 테스트 컴파일에 영향이 없습니다.@@ -0,0 +21,4 @@//! is silently dropped — extractor failure must never fail the whole//! document.use std::io::Cursor;EXIF 화이트리스트 키 네이밍이 PascalCase (
Make/Model/DateTimeOriginal/Orientation/Software) 와 snake_case (gps_lat/gps_lon) 로 갈라져 있습니다. PascalCase 쪽은 EXIF 표준 태그명을 그대로 따랐고 snake_case 쪽은 합성된 파생값이라 의도가 다른 건 이해하지만, JSON consumer 입장에서 같은 객체 안 키 두 종류가 섞여 있는 건 약간 거슬립니다. 두 가지 정리 방향이 있습니다:GPSLatitude/GPSLongitude로 PascalCase 통일 — EXIF 태그명을 보존하면서 "이미 ref 와 합쳐 decimal 로 변환된 값" 임은 wire schema 문서에서 별도 주석.make/model/date_time_original/ ...).결정은 다른 wire schema (
docs/wire-schema/v1/) 의 표기 컨벤션을 따르는 쪽이 좋겠습니다. 어느 쪽이든 한 PR 로 정해 두면 P6-2 (OCR) / P6-3 (caption) 가 메타데이터를 추가할 때 같은 규칙을 따를 수 있습니다.@@ -0,0 +38,4 @@if let Some(s) = ascii_field(&exif, Tag::DateTimeOriginal, In::PRIMARY) {if let Some(iso) = exif_datetime_to_iso(&s) {out.insert("DateTimeOriginal".into(), JsonValue::String(iso));Rust 2024 의 let-chain 으로 두
if let을 하나로 합칠 수 있어 한 단 들여쓰기를 줄일 수 있습니다.같은 패턴이 GPS 분기 (lat/lon 분기에서
if let Some(num) = serde_json::Number::from_f64(...)) 에도 적용됩니다.@@ -0,0 +70,4 @@}fn ascii_field(exif: &exif::Exif, tag: Tag, ifd: In) -> Option<String> {let f = exif.get_field(tag, ifd)?;ascii_field와u32_field의ifd: In인자가 호출부에서 항상In::PRIMARY만 받습니다 (gps_decimal내부ascii_field(exif, ref_tag, In::PRIMARY)까지 포함해 5 곳 모두). 현재로선 dead flexibility 라 함수 시그니처 노이즈만 늘리는 모양새인데, 단순히 함수 본문에서In::PRIMARY로 인라인하고 인자를 떨어뜨리는 게 더 정직해 보입니다. 추후 보조 IFD 까지 읽어야 할 일이 생기면 그때 매개변수를 부활시키면 되고, 그 시점이 되면 호출부도 PRIMARY 가 아닌 IFD 를 의식적으로 넘기게 되니 의미가 살아납니다.@@ -0,0 +81,4 @@let exif_map = exif_extract::extract_whitelisted(bytes);let (span, dims_value, decode_warning) = match &dim_outcome {dims::DimOutcome::Ok { width, height, format } => {변수명
decode_warning이 약간 좁아 보입니다. 이 갈래는 디코더 에러뿐 아니라 16k cap 초과 (DimOutcome::Failed { reason: "image dimensions ... exceed cap ..." }) 도 같은 슬롯에 담습니다. 호���부 코드를 따라 읽다 보면decode_warning = Some(reason)인데 reason 이 "exceed cap" 인 케이스를 한 박자 늦게 인지하게 됩니다.dim_warning정도로 바꾸면 두 출처를 모두 자연스럽게 포괄합니다.@@ -0,0 +236,4 @@/// Stable ASCII path constant — avoids depending on `Path::new` or the/// host's path separator in the call sites.#[allow(dead_code)]pub fn fake_path(p: &str) -> &Path {fake_path와 그 위use std::path::Path;가 어느 테스트에서도 호출되지 않는 dead helper 입니다.#![allow(dead_code)]로 경고가 묻혀 있지만, 워크스페이스의 다른 fixture 모듈들은 실제로 호출되는 헬퍼만 두는 일관성을 지키고 있으니 이 함수와 import 를 제거해 주세요.회차 2 — 회차 1 지적 모두 정확히 반영되었습니다 (
Cargo.tomldeps 정리,dim_warningrename,In인자 제거, let-chain 적용, snake_case ��� 통일,fake_path제거). 회차 1 에서 미처 못 본 EXIF 안전성 / 디버깅 항목 몇 건이 더 있어 한 번 더 정리하고 싶습니다.이번 라운드의 핵심은 EXIF 파싱 정확성:
gps_decimal의 좌표 범위 검증 누락 (±90 / ±180) — 위도 200° 같은 비정상 값이 wire 에 그대로 흘러갈 수 있습니다.부수 항목:
read_from_container실패 시tracing::debug!한 줄 추가 (운영시 손상 EXIF 디버깅).dims.rs의match Some/None을.context()?로 압축.Vec::with_capacity(3)의 의미 명시 (분기 또는 주석).칭찬: 회차 1 에서 짚은 EXIF 키 네이밍을
docs/wire-schema/v1/의 snake_case 컨벤션과 정합되도록 (make/model/date_time_original/gps_lat/ ...) 모두 통일하면서 모듈 doc 의 표까지 같이 갱신해 둔 것은 후속 작업 (P6-2 / P6-3) 에서 동일 컨벤션을 자연스럽게 따라가도록 만들어 주는 좋은 마감이었습니다.@@ -0,0 +37,4 @@.with_guessed_format().map_err(|e| anyhow::anyhow!("io error guessing format: {e}"))?;let format = match reader.format() {match reader.format() { Some(f) => f, None => anyhow::bail!("…") }패턴은.context(…)?로 한 줄에 들어갑니다:anyhow::Contextimport 만 추가하면 됩니다. 코드 의미는 동일하면서 흐름이 짧아집니다.@@ -0,0 +35,4 @@let mut out = Map::new();let exif = match Reader::new().read_from_container(&mut Cursor::new(bytes)) {Ok(e) => e,Err(_) => return out,read_from_container의Err(_)를 그냥 흘려버리는데, 이 갈래가 "EXIF 자체 없음" 과 "EXIF 가 있는데 파서가 손상으로 보고 거부" 두 케이스를 묶어 버립니다. 운영시 후자가 의심스러울 때 단서가 전혀 없습니다. provenance 까지 채울 정도는 아니지만tracing::debug!한 줄은 거의 비용 없이 디버깅에 도움이 됩니다:(crate 가 이미
tracing을 의존성에 갖고 있어 추가 비용 없음.)@@ -0,0 +133,4 @@/// reference tag. Returns `None` if either tag is missing or shaped/// unexpectedly.fn gps_decimal(exif: &exif::Exif, value_tag: Tag, ref_tag: Tag) -> Option<f64> {let f = exif.get_field(value_tag, In::PRIMARY)?;GPS DMS triple 의 입력값 sanity check 가 없습니다. 비정상 EXIF (예: deg=200, min=0, sec=0) 가 들어오면
decimal = 200.0이 그대로 나가서gps_lat: 200.0같은 위도가 wire 에 실립니다. 다운스트림이 위도/경도 가정으로 mapping/index 를 돌릴 때 안전하지 않습니다.반환 직전 범위 체크를 권장합니다 (위도 ±90, 경도 ±180):
드롭 정책은 "파싱 실패 = silent drop" 인 모듈 전체 약속과도 부합합니다.
@@ -0,0 +142,4 @@let min = rational_to_f64(&dms[1])?;let sec = rational_to_f64(&dms[2])?;let mut decimal = deg + min / 60.0 + sec / 3600.0;if let Some(reference) = ascii_field(exif, ref_tag) {GPSLatitudeRef / GPSLongitudeRef 가 아예 없을 때 현재 구현은 부호 적용 단계를 그냥 건너뛰어 양수 decimal 을 반환합니다. 결과적으로
gps_lat만 보고는 N 인지 S 인지 알 수 없는 모호한 값이 나갑니다. EXIF 표준상 ref 는 GPS 좌표와 함께 항상 존재해야 하므로, ref 가 없는 입력은 손상된 메타데이터로 보고 좌표 자체를 드롭하는 게 안전합니다:(
if let을 단순?로 교체.)@@ -0,0 +129,4 @@});let now = OffsetDateTime::now_utc();let mut events: Vec<ProvenanceEvent> = Vec::with_capacity(3);Vec::with_capacity(3)인데 일반 경로는 항상 2개 (Discovered + Parsed) 만 쌓고, dim_warning 가 있을 때만 3 번째가 추가됩니다. 상수 3 은 "warning 까지 포함��� 최대치" 의 의미를 코드만 봐서는 알기 어렵습니다. 정확히 분기시키거나, 못 해도 짧은 주석 한 줄을 권장합니다:사소하지만 향후 누군가 Normalized / OcrApplied 등 단계를 추가할 때 capacity 를 같이 손볼 단서가 됩니다.
- src/exif_extract.rs: • `gps_decimal` 에 ±90 / ±180 범위 검증 추가. 비정상 EXIF (예: 위도 300°) 가 들어와도 wire 에 흘러나가지 않고 silent drop. • GPSLatitudeRef / GPSLongitudeRef 가 빠진 좌표는 양수 가정으로 내보내지 않고 None 반환 — 모호한 부호를 그대로 두는 대신 손상된 메타데이터로 처리. • `read_from_container` 실패 시 `tracing::debug!` 한 줄로 사유 기록 (운영시 \"EXIF 없음\" vs \"EXIF 손상\" 구분 단서). - src/dims.rs: `match Some/None` 을 `anyhow::Context::context()?` 로 압축. import 한 줄 추가. - src/lib.rs: `Vec::with_capacity` 를 dim_warning 분기에 따라 `2` / `3` 으로 정확히 맞추고 의미 주석 한 줄 추가. - tests/common/mod.rs: `build_exif_blob_gps` 를 `GpsFlavor` 파라미터로 일반화 (`Valid` / `NoRef` / `OutOfRange`). JPEG 스플라이스 로직은 `splice_exif_into_jpeg` 헬퍼로 추출. - tests/extractor.rs: 회귀 테스트 2건 추가 — `*Ref` 누락 좌표 드롭, out-of-range 위도 드롭 (경도는 정상 통과 검증). cargo test -p kebab-parse-image — 16건 (4 unit + 12 integration) pass. cargo clippy -p kebab-parse-image --all-targets -- -D warnings — pass.회차 3 — 회차 2 의 GPS 안전성 / 디버깅 / Vec capacity 분기 / dims.rs
.context()?정리 모두 정확히 반영되었고, GPS missing-ref + out-of-range 회귀 테스트 2건이 추가되었습니다 (총 16건). 핵심 동작 contract 와 안전성은 더 손볼 곳이 보이지 않습니다.남은 항목은 모두 cosmetic nit 입니다:
dims.rs의with_guessed_format()뒤map_err— 회차 2 정리와 짝을 맞춰?만으로 정리.lib.rs의(*format).to_string()— 자동 deref 로format.to_string().tests/common/mod.rs의ImageFixture::workspace_root/config가시성 — 외부에서 직접 읽지 않으므로 비공개로.회차 한 번 더 도는 비용보다 cleanup 누락이 머지 후 별도 PR 로 이어지는 비용이 크다는 가이드를 따라 REQUEST_CHANGES 로 둡니다. 반영되면 다음 회차에서 APPROVE 가능 예정입니다.
칭찬: GPS DMS 처리 (
gps_decimal) 의 doc-comment 가 "None 을 반환하는 모든 케이스" 를 bullet 로 명시해 두어 향후 maintainer 가 정책을 한 눈에 파악할 수 있게 정리되었습니다. P6-2 / P6-3 의 OCR / caption stub 도 같은 doc-comment 톤을 유지하면 일관됩니다.@@ -0,0 +35,4 @@pub(crate) fn probe(bytes: &[u8]) -> Result<DimOutcome> {let reader = ImageReader::new(Cursor::new(bytes)).with_guessed_format().map_err(|e| anyhow::anyhow!("io error guessing format: {e}"))?;회차 2 의
match Some/None→.context()?정리와 짝을 맞춰서 이 줄도 같이 정리하면 좋겠습니다.with_guessed_format는Result<_, std::io::Error>를 돌려주고,anyhow::Error가io::Error의From변환을 자동으로 갖고 있어서map_err없이?만으로 충분합니다. 게다가 인메모리Cursor라 io 에러 자체가 사실상 발생하지 않는 갈래라 message 도 dead-only:부가설명을 굳이 남기고 싶으면 같은 패턴으로
.context("reading image header")?로 통일해도 좋습니다.@@ -0,0 +86,4 @@dims.insert("w".into(), Value::Number((*width).into()));dims.insert("h".into(), Value::Number((*height).into()));dims.insert("format".into(), Value::String((*format).to_string()));(format의 타입이&&'static str이라 명시적 deref 없이도.to_string()자동 호출이 가능합니다.(*format).to_string()→format.to_string()으로 정리하면 다른 줄의(*width).into()/*width패턴과 시각적 일관성이 살짝 흐트러지는 것은 맞지만,*가 필요 없는 자리에 박아 놓으면 "왜 이 자리만 deref?" 의문이 생길 수 있습니다. 사소합니다.@@ -0,0 +210,4 @@/// per §4.2 — this matches what `kebab-source-fs` does in production.pub struct ImageFixture {pub asset: RawAsset,pub workspace_root: PathBuf,ImageFixture::workspace_root/config두 필드는ctx()내부에서만 빌려주고, 어떤 통합 테스트도 외부에서 직접 읽지 않습니다 (asset만fx.asset.media_type,fx.asset.asset_id식으로 직접 접근). 두 필드��� 비공개로 내려도 외부 API 가 깔끔해집니다:언젠가 직접 접근이 필요해지면 그때 다시
pub으로 풀면 됩니다.회차 4 — 회차 3 cosmetic 3건 (
dims.rs의.context()?통일,lib.rs의 deref 정리,tests/common의ImageFixture가시성 축소) 모두 정확히 반영되었습니다. 추가로 손볼 actionable 한 항목이 더 보이지 않습니다.전체 회차 정리:
머지 가능합니다. 사용자가 Gitea UI 에서 머지해 주세요:
#32
"Delete branch after merge" 체크 권장. 로컬 브랜치는 머지 후
git fetch -p+git branch -d feat/p6-1-image-extractor-exif로 정리.(칭찬)
gps_decimal의 doc-comment 가 "None을 반환하는 모든 분기" 를 bullet 로 정확히 나열해 주어 좋습니다. 향후 GPS 처리 정책이 바뀔 때 (예: HEIC 의 OffsetTime 까지 포함, 또는 ICC 위치 보정 적용) 어디를 손봐야 하는지 한눈에 보입니다. P6-2 / P6-3 의 OCR / caption 함수도 같은 톤으로 "실패 분기 = bullet" 패턴을 유지하면 모듈 간 일관성이 살아납니다.@@ -0,0 +102,4 @@buf.into_inner()}/// Selector for which GPS shape the test fixture should embed.(칭찬) GPS 안전성 검증을 단일
GpsFlavorenum 하나로 압축한 게 좋습니다. fixture builder 가 늘어나도 테스트마다 별도의 boilerplate JPEG 헤더 splice 코드를 또 적을 필요가 없고, 새 케이스 (예: zero-denom Rational) 를 추가할 때도 한 곳만 손보면 됩니다.