feat(p10-1a-1): code ingest framework — wire schema + parse-code crate + filter flags #139
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: altair823-org/kebab#139
Reference in New Issue
Block a user
Delete Branch "spec/p10-code-ingest-design"
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?
Goal
Phase 1A-1 of the code ingest design (
docs/superpowers/specs/2026-05-15-kebab-code-ingest-design.md). Land the framework surface for code ingest — wire schema (additive minor), CLI filter flags, ignore policy, skip policy infrastructure,kebab-parse-codecrate skeleton,[ingest.code]config section — without enabling any code chunker. 1A-2 plugs in the Rust AST chunker on top.What's in
Citation::Codevariant,SearchHit.repo/code_lang(optional),IngestReport5 skip counters +SkipExamples,Metadata4 신규 필드 (repo / git_branch / git_commit / code_lang).kebab-parse-code:lang::code_lang_for_path(extension → 식별자),repo::detect_repo(gix walk-up),skip::is_generated_file/is_oversized/BUILTIN_BLACKLIST(6 entry safety net)..gitignorehonor + built-in blacklist + 카테고리별 skip 카운터 분류. 우선순위: built-in > .gitignore > .kebabignore.@generated,DO NOT EDIT등 7 markers, case-insensitive) + size cap (max_file_bytes/max_file_lines).[ingest.code]절 (7 필드, 모두 default).--repo,--code-lang,--media codefilter (1A-1 시점에는 hit 0).tasks/p10/신설.What's NOT in
codeCitation variant 는 정의됐지만 아무도 생성하지 않음).Verification
cargo test --workspace --no-fail-fast -j 1: 685 passed, 0 failed, 28 ignored.cargo clippy --workspace --all-targets -- -D warnings: clean.kebab init+kebab ingest --json): 새 5 skip counter + skip_examples 모두 surface, 기존 wire shape (scanned / new / skipped / ...) 무영향.repo/code_lang정상 omit.kebab schema --json:code_lang_breakdown/repo_breakdown빈 map.Implementation note
Plan (
docs/superpowers/plans/2026-05-15-p10-1a-1-code-ingest-framework.md) 의 21 task 를 subagent-driven 으로 실행. 각 task 가 implementer + spec reviewer + code quality reviewer 3-stage. 도중 follow-up fix 5건 (test-only SearchHit construction sites missed by Task 2, kebab-parse-code manifest fields, .gitignore negation guard, Task 11 review cleanup, Task 16 wire.rs Stats fixture).Links
docs/superpowers/specs/2026-05-15-kebab-code-ingest-design.mddocs/superpowers/plans/2026-05-15-p10-1a-1-code-ingest-framework.mdtasks/p10/p10-1a-1-code-ingest-framework.mdtasks/p10/INDEX.md21 task plan: kebab-core 도메인 타입 (Citation::Code variant, SearchHit repo/code_lang, IngestReport skip counters, Metadata extension), 새 kebab-parse-code crate (lang/repo/skip 모듈, gix dep), kebab-source-fs gitignore+blacklist 통합, kebab-config [ingest.code] 절, kebab-cli --repo/--code-lang flag, wire schema JSON 갱신, frozen design doc 갱신, README/HANDOFF/SMOKE 갱신, task index. 각 task 가 5-step TDD cycle (test fail → impl → pass → commit). 코드 chunker 는 1A-1 에 없음 — 1A-2 에서 추가. spec 의 Citation::Code 예시가 기존 5 variants 의 flat wire 형태와 안 맞아서 (`code: {...}` 중첩이 아니라 top-level field) 같이 fix. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>Task 16's new code_lang_breakdown / repo_breakdown fields broke the existing schema_wrapper_tags_schema_version test in wire.rs which constructs Stats { ... } literally. Use ..Default::default() since Stats now derives Default. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>회차 1 — 21 task 모두 per-task review 통과한 상태로 PR 등록됐는데, 전체 diff 다시 훑어보니 doc 레이어에서 4 건 actionable 발견. ���두 doc 일관성 / accuracy 이슈로 코드 자체는 무관.
주요 이슈:
repo필드가 들어가 있는데Citation::Code에 그런 필드 없음 (actual enum: path / line_start / line_end / symbol / lang). 그리고 같은 PR 안의 2026-05-15 spec §3.1 (commit005a901) 은 flat form 으로 적었는데 2026-04-27 frozen design 의 같은 variant 는 nested form 이라 두 spec 이 서로 모순.repo: null, code_lang: null을 적어놓고 주석에 "omitted when null" — 모순 (실제 wire 는 키 자체가 빠짐).**10**(다른 row 는**P0**/**P5**식).[--media code]가 별도 flag 처럼 두 번 나타남.코드 자체 / 테스트 / wire schema JSON / chunker 흐름은 모두 통과. 다음 회차에서 위 4건 후속 commit 으로 정리.
@@ -20,6 +20,7 @@ P0–P5 + P6 + P7 + P9-1/2/3/4 (Library / Search / Ask / Inspect) 머지 완료.| **P7** | PDF text + page citation | `kebab-parse-pdf` | P5 | ✅ 완료 (3/3 component, page-level chunker + ingest wiring) || **P8** | 음성 transcription + timestamp citation | `kebab-parse-audio` | P5 | ⏸ 보류 (whisper-rs 시스템 dep brainstorm 필요) || **P9** | TUI + desktop app | `kebab-tui`, `kebab-desktop` | P5 | 🟡 진행 (4/5 component — P9-1/2/3/4 완료 [Library / Search / Ask / Inspect], P9-5 desktop 예정 · 도그푸딩 피드백 **20/20 ✅**) || **10** | code ingest framework | `kebab-parse-code` | P5 | 🟡 진행 중 (1A-1 머지 직전) — 1A-1 머지 시점 wire schema additive minor + 새 crate kebab-parse-code skeleton 동결, 실제 code chunker 는 1A-2 부터 |Phase 식별자가
**10**— 다른 row 는**P0**/**P5**/**P9**처럼Pprefix. 일관성 위해**P10**으로.@@ -72,3 +72,3 @@| `kebab init` | XDG 경로에 데이터 디렉토리 + config.toml 생성 || `kebab ingest [<path>]` | Markdown / 이미지 / PDF 색인 (idempotent). TTY 에서는 stderr 진행 바, non-TTY (CI / pipe) 는 stderr 한 줄씩, `--json` 은 stdout 에 `ingest_progress.v1` 라인 streaming 후 마지막에 `ingest_report.v1`. Ctrl-C 한 번이면 현재 asset 마무리 후 abort (부분 commit 보존, idempotent re-run), 두 번째 Ctrl-C 는 hard exit. Markdown title 이 frontmatter 에 없어도 첫 H1 → H2 → 첫 paragraph 80 자 → 파일명 순으로 자동 채움 (parser_version `md-frontmatter-v2`) — 기존 색인된 doc 도 다음 ingest 에서 새 title 로 갱신. **Incremental** (p9-fb-23): 두 번째 이후의 ingest 는 변하지 않은 doc (blake3 + parser/chunker/embedder version 모두 동일) 의 parse/chunk/embed/vector upsert 를 자동 스킵. final summary 에 `N unchanged` 카운트 표시. `--force-reingest` 로 skip 무시 강제 재처리. **지원 형식** (extractor 자동 결정 — config 에 명시 불가): Markdown (`.md`), 이미지 (`.png` / `.jpg` / `.jpeg`, OCR + caption), PDF (`.pdf`). 다른 확장자는 자동 skip — `IngestItem.warnings` 에 사유 (`"unsupported media type: .docx"` 등), `IngestReport.skipped_by_extension` 에 카운트 분류, CLI / TUI summary 에 breakdown 표시. || `kebab search --mode {lexical,vector,hybrid} "<query>" [--no-cache] [--max-tokens N] [--snippet-chars N] [--cursor <opaque>] [--tag T] [--lang L] [--path-glob G] [--trust-min LEVEL] [--media TYPE] [--ingested-after RFC3339] [--doc-id ID] [--trace] [--bulk]` | 검색. hybrid는 RRF fusion, citation 포함. 같은 process 안에서 동일 query (NFKC + trim + lowercase 정규화) 반복 시 in-process LRU 캐시 hit (capacity = `[search] cache_capacity`, default 256). `--no-cache` 로 강제 bypass — 디버깅용. ingest commit 발생 시 `kv['corpus_revision']` bump 으로 모든 entry 자동 stale. **`--max-tokens` / `--snippet-chars` / `--cursor` (p9-fb-34)** — agent budget controls. `--json` 출력은 `search_response.v1` wrapper (`{hits, next_cursor, truncated}`) — pre-fb-34 의 bare array 와 호환 안 됨. mismatched cursor → `error.v1.code = stale_cursor`. **filter flags (p9-fb-36):** `--tag` 는 반복 가능 flag (`--tag rust --tag async`) 로 OR 매칭, `--media` 는 `,` 구분 다중 값 OR 매칭, 나머지 flags 간은 AND 조합. `--trust-min` 은 `primary\|secondary\|generated` 중 하나 (해당 level 이상 포함). `--ingested-after` 는 RFC3339 UTC — 파싱 실패 시 `error.v1.code = config_invalid` (exit 2). `--media md` 는 `markdown` alias 로 정규화. 알 수 없는 `--media` 값은 무조건 empty hits (오류 아님). **`--trace` (p9-fb-37)** — `search_response.v1.trace` 에 lexical / vector pre-fusion 후보 + RRF union + per-stage timing (`lexical_ms` / `vector_ms` / `fusion_ms` / `total_ms`) 노출. trace 요청은 캐시 우회 (`--no-cache` 없이도 항상 cold). **`--bulk` (p9-fb-42)** — stdin ndjson 으로 N query 한 번에 실행. `--json` 면 stdout per-query ndjson (`bulk_search_item.v1`) + stderr summary (`bulk_summary: total=N succeeded=S failed=F`). Cap 100. agent 가 query decomposition 후 sub-query 일괄 실행 시 single round-trip — App instance 재사용으로 캐시 / embedder cold-start 비용 한 번만. Per-query failure 는 item 의 `error` (error.v1) 에 격리, 다른 query 계속 진행. || `kebab search --mode {lexical,vector,hybrid} "<query>" [--no-cache] [--max-tokens N] [--snippet-chars N] [--cursor <opaque>] [--tag T] [--lang L] [--path-glob G] [--trust-min LEVEL] [--media TYPE] [--ingested-after RFC3339] [--doc-id ID] [--trace] [--bulk] [--repo NAME ...] [--code-lang LIST] [--media code]` | 검색. hybrid는 RRF fusion, citation 포함. 같은 process 안에서 동일 query (NFKC + trim + lowercase 정규화) 반복 시 in-process LRU 캐시 hit (capacity = `[search] cache_capacity`, default 256). `--no-cache` 로 강제 bypass — 디버깅용. ingest commit 발생 시 `kv['corpus_revision']` bump 으로 모든 entry 자동 stale. **`--max-tokens` / `--snippet-chars` / `--cursor` (p9-fb-34)** — agent budget controls. `--json` 출력은 `search_response.v1` wrapper (`{hits, next_cursor, truncated}`) — pre-fb-34 의 bare array 와 호환 안 됨. mismatched cursor → `error.v1.code = stale_cursor`. **filter flags (p9-fb-36):** `--tag` 는 반복 가능 flag (`--tag rust --tag async`) 로 OR 매칭, `--media` 는 `,` 구분 다중 값 OR 매칭, 나머지 flags 간은 AND 조합. `--trust-min` 은 `primary\|secondary\|generated` 중 하나 (해당 level 이상 포함). `--ingested-after` 는 RFC3339 UTC — 파싱 실패 시 `error.v1.code = config_invalid` (exit 2). `--media md` 는 `markdown` alias 로 정규화. 알 수 없는 `--media` 값은 무조건 empty hits (오류 아님). **`--trace` (p9-fb-37)** — `search_response.v1.trace` 에 lexical / vector pre-fusion 후보 + RRF union + per-stage timing (`lexical_ms` / `vector_ms` / `fusion_ms` / `total_ms`) 노출. trace 요청은 캐시 우회 (`--no-cache` 없이도 항상 cold). **`--bulk` (p9-fb-42)** — stdin ndjson 으로 N query 한 번에 실행. `--json` 면 stdout per-query ndjson (`bulk_search_item.v1`) + stderr summary (`bulk_summary: total=N succeeded=S failed=F`). Cap 100. agent 가 query decomposition 후 sub-query 일괄 실행 시 single round-trip — App instance 재사용으로 캐시 / embedder cold-start 비용 한 번만. Per-query failure 는 item 의 `error` (error.v1) 에 격리, 다른 query 계속 진행. **code corpus filters (p10-1A-1):** `--repo` 는 반복 가능 (`--repo kebab --repo other`) OR 매칭. `--code-lang` 는 반복 또는 comma 다중 값 (`--code-lang rust,python`), 알 수 없는 값은 빈 hits. `--media code` 는 Tier 1/2/3 모든 code chunk 포함. 1A-1 시점에서는 indexed 된 code chunk 가 없어 filter 가 항상 빈 결과 — 1A-2 (Rust AST chunker) 머지 이후 실효. |[--repo NAME ...] [--code-lang LIST] [--media code]중[--media code]는 별도 flag 가 아니라 기존--media TYPEflag 의 한 가지 값. 같은 synopsis 안에[--media TYPE]이 이미 있어서 두 번 등장하게 됨. 제거하고 뒤쪽 prose (--media code는 Tier 1/2/3 모든 code chunk 포함) 만 두는 게 깔끔.@@ -183,2 +184,3 @@"caption": { "model": "qwen2.5-vl:7b" },"time": { "start_ms": 822000, "end_ms": 850000, "speaker": "S1" }"time": { "start_ms": 822000, "end_ms": 850000, "speaker": "S1" },"code": { "start": 10, "end": 42, "lang": "rust", "repo": "kebab", "symbol": "fn ingest" }codevariant 예시에repo필드가 있는데, 실제Citation::Codeenum 에는 repo 필드 없음 (crates/kebab-core/src/citation.rs확인 — 필드 5개:path,line_start,line_end,symbol,lang).repo는SearchHit/Metadata에만 살고, Citation 에는 없음. 이 예시 그대로 두면 spec 가 actual wire 와 안 맞아서 향후 consumer 가 헷갈림.또
start/endvsline_start/line_end이슈도 있음 — 위에 있는 nested-form 그룹 (line: {start, end}, page: {page}, ...) convention 을 따른 거라면 OK 지만, 실제 Rust 코드는 flat enum (#[serde(tag = "kind")]) 이라 wire 출력에는"line_start": 142, "line_end": 168처럼 top-level. 2026-05-15 spec §3.1 (같은 PR 의 커밋005a901) 에서는 flat 형태로 적었는데 frozen design 의 같은 항목은 nested 로 남아 있어서 두 spec 이 서로 다른 형태를 보여줌. 일관성 위해 정리하는 게 좋겠음.@@ -215,2 +229,3 @@"embedding_model": "multilingual-e5-large","chunker_version": "md-heading-v1""chunker_version": "md-heading-v1","repo": null, // p10-1A-1: optional, omitted when null (code corpus only)주석
// p10-1A-1: optional, omitted when null과 값null이 모순. 실제SearchHit.repo/code_lang는#[serde(default, skip_serializing_if = "Option::is_none")]라None일 때 키 자체가 JSON 에서 빠짐 (null 값으로 등장 안 함). 예시에null적어두면 reader 가 '아 null 로 들어오는구나' 라고 잘못 이해. 두 옵션:p10-1A-1: 코드 hit 에서만 surface — markdown hit 에는 absent)."kebab"/"rust"같은 sample 로 채우고 주석을optional로.회차 2 — 회차 1 의 4 건 actionable 모두 반영 확인 (
7961f88):code항목 제거 +구현 노트 (wire 실제 형태)para 추가 (모든 6 variant 의 nested-vs-flat 차이 설명) + code variant 별도 block 으로 flat 형태 정확히 명시 (path / line_start / line_end / symbol / lang,repo없음). 2026-05-15 spec 과 일치.null라인 두 개 제거, inline 주석 한 줄로 정정 ('markdown hit 에는 키 absent, code hit 에서만 surface').**10**→**P10**(다른 row 와 prefix 일관).[--media code]제거.추가 actionable 없음. 코드 / wire schema / 테스트 모두 그대로. 머지 가능.