Files

altair823 7a49c8a29b feat(kebab-normalize): p9-fb-07 markdown title fallback chain

`kebab-normalize::derive_title(frontmatter_title, blocks, file_stem)` 가
다음 단계로 비어있지 않은 첫 결과를 사용:

1. frontmatter `title` (trim 후)
2. 첫 H1 텍스트
3. 첫 H2 텍스트
4. 첫 Paragraph (Quote / List / Code / Table / ImageRef 제외) 의 첫 80 자
5. 파일 stem (확장자 제외)
6. (sentinel) `"untitled"` — 위 다섯 단계가 모두 blank 인 병적 케이스

선택된 문자열은 NFC 정규화. 빈 문자열은 절대 반환하지 않음.

`build_canonical_document` 가 metadata lift 직후 helper 호출. 기존 단순
lift 로직 (metadata.user["title"] → CanonicalDocument.title) 은 fallback
chain 의 1 단계 입력으로 자리 이동.

`KEBAB_PARSE_MD_VERSION` 상수를 `pulldown-cmark-0.x` → `md-frontmatter-v2`
로 bump. parser_version 변경 → §4.2 doc_id 입력 변화 → 기존 markdown
doc 의 `doc_id` 갱신, 다음 ingest 시 idempotent upsert 로 자동 재처리
(design §9 cascade). `kebab-store-sqlite` 의 snapshot fixture 도 같은
literal 로 갱신.

기존 M7 정책 ("metadata.user[\"title\"] = '' 가 빈 title 로 lift") 은
폐기. 빈 문자열 입력은 fallback chain 을 타고 file stem 까지 떨어진다.
spec p9-fb-07 line 37: "빈 문자열 반환 금지".

테스트 (kebab-normalize):
- 8 개 단위 테스트 (각 fallback 단계 + NFC + sentinel)
- `build_canonical_document` 통합 테스트 2 개 (H1 / file stem)
- 기존 M7 테스트 2 개를 새 정책에 맞춰 갱신

문서:
- README: `kebab ingest` 행에 "title 자동 채움" 안내 + 기존 doc 도
  다음 ingest 에서 갱신
- HANDOFF: 2026-05-03 머지 후 발견 entry
- spec status: `planned` → `in_progress`

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-03 01:22:34 +00:00

2.1 KiB

Raw Blame History

phase, component, task_id, title, status, depends_on, unblocks, contract_source, contract_sections, source_feedback

phase

component

task_id

title

status

depends_on

unblocks

contract_source

contract_sections

source_feedback

kebab-parse-md + kebab-normalize

p9-fb-07

Markdown title fallback chain (frontmatter → H1 → H2 → first paragraph → filename)

in_progress

../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md

§3.5 ParsedDoc

§5.5 CanonicalDocument

p9-dogfooding-feedback.md item 5

p9-fb-07 — Title fallback

Goal

frontmatter title / 첫 H1 둘 다 없는 markdown 도 의미 있는 title 표시. fallback chain 명시 + parser_version cascade.

Allowed dependencies

기존 kebab-parse-md / kebab-normalize. 신규 X.

Public surface

kebab-normalize::derive_title(parsed: &ParsedDoc, file_stem: &str) -> String 가 chain 구현. CanonicalDocument.title 채움.

Behavior contract

fallback 우선순위:

frontmatter title (기존)
첫 H1 텍스트 (기존)
첫 H2 텍스트 (신규)
첫 non-empty paragraph 의 첫 80 자 (인용 / list 제외)
파일명 (확장자 제외, kebab-case 유지)

빈 결과 / whitespace 만이면 다음 단계로 진행. 모든 단계 실패 시 (frontmatter only no body file) 파일명. 빈 문자열 반환 금지.

parser_version (현재 md-frontmatter-v1) → md-frontmatter-v2 bump. 기존 doc 은 next ingest 시 재처리 (same doc_id recipe → upsert).

Test plan

kind	description
unit	frontmatter title only → 1단계
unit	H2 부터 시작 → 3단계
unit	표만 있는 doc → 4단계 (paragraph 없음 → 5단계 filename)
unit	한글 H1 → NFC 정규화된 title
snapshot	corpus 의 python-360-... → "Annotation issues at runtime"

DoD

cargo test -p kebab-parse-md -p kebab-normalize 통과
parser_version 갱신 (md-frontmatter-v2)
HOTFIXES X — bump 은 정상 cascade 동작
사용자에게 "title 비어 있던 doc 은 kebab ingest 다시 돌리면 채워짐" 안내 (README 또는 changelog)

Out of scope

PDF / 이미지 doc 의 title fallback (별도 task — 다른 parser)
AI 로 title 추출 (P+)

2.1 KiB Raw Blame History