vibe-commander 0.1.0

package/dist/core/parsers/metadata-parser.js

@@ -0,0 +1,133 @@
+/**
+ * 메타데이터 테이블 파서 — Layer 1 순수 함수
+ *
+ * 계획서 마크다운의 메타데이터 테이블(2-column key-value)에서
+ * 유닛 메타정보를 추출한다.
+ *
+ * 설정의 `metadataTable` 필드명으로 시맨틱 키(unitId, phase, depends)에 매핑.
+ * 테이블이 없으면 모든 필드가 null인 결과 반환 (Graceful Degradation).
+ *
+ * @module
+ */
+import { ok } from '../../types/index.js';
+import { normalizeLineEndings, isNoneDependency } from './md-utils.js';
+/**
+ * 마크다운 2-column 테이블에서 메타데이터를 파싱한다
+ *
+ * 첫 번째 2-column 테이블을 찾아 key-value 쌍으로 추출하고,
+ * 설정의 필드명으로 시맨틱 키(unitId, phase, depends)에 매핑한다.
+ *
+ * @param content - 마크다운 전체 내용
+ * @param tableConfig - 메타데이터 테이블 필드명 매핑 설정
+ * @returns 파싱된 메타데이터 결과를 포함한 ToolResult
+ *
+ * @example
+ * ```typescript
+ * const content = '| 항목 | 내용 |\n|---|---|\n| Unit ID | U-005 |\n| Phase | MVP |';
+ * const config = { idField: 'Unit ID', phaseField: 'Phase', dependsField: '의존성' };
+ * const result = parseMetadataTable(content, config);
+ * if (result.success) {
+ *   // result.data.unitId === 'U-005'
+ * }
+ * ```
+ */
+export function parseMetadataTable(content, tableConfig) {
+    const normalized = normalizeLineEndings(content);
+    const raw = extractFirstTwoColumnTable(normalized);
+    const dependsRaw = raw[tableConfig.dependsField];
+    const depends = dependsRaw
+        ? dependsRaw
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => !isNoneDependency(s))
+        : [];
+    return ok({
+        unitId: raw[tableConfig.idField],
+        phase: raw[tableConfig.phaseField],
+        depends,
+        raw,
+    });
+}
+// ── 내부 헬퍼 ──
+/** separator 행 패턴 (|---|---| 형식, 정렬 콜론 허용) */
+const SEPARATOR_RE = /^\|(\s*:?-+:?\s*\|)+$/;
+/**
+ * 라인이 테이블 행인지 판별한다
+ *
+ * `|`로 시작하고 `|`로 끝나는 행을 테이블 행으로 인식.
+ */
+function isTableRow(line) {
+    return line.startsWith('|') && line.endsWith('|');
+}
+/**
+ * 라인이 테이블 separator 행인지 판별한다
+ *
+ * `|---|---|` 패턴을 매칭. 정렬 콜론(`:---:`, `:---`, `---:`) 허용.
+ */
+function isSeparatorRow(line) {
+    return SEPARATOR_RE.test(line);
+}
+/**
+ * 테이블 행에서 셀 값을 추출한다
+ *
+ * 양쪽 `|`를 제거하고 `|`로 분리한 뒤 각 셀을 trim.
+ */
+function parseTableCells(line) {
+    return line
+        .slice(1, -1)
+        .split('|')
+        .map((c) => c.trim());
+}
+/**
+ * 문서에서 첫 번째 2-column 테이블의 key-value 맵을 추출한다
+ *
+ * 알고리즘:
+ * 1. separator 행은 헤더 후보에서 제외
+ * 2. 2개 컬럼의 헤더 행 탐색
+ * 3. 바로 다음 행이 separator인지 확인
+ * 4. separator 이후 데이터 행들을 key-value로 파싱
+ * 5. 비테이블 행 또는 새 separator를 만나면 종료
+ */
+function extractFirstTwoColumnTable(content) {
+    const lines = content.split('\n');
+    const raw = {};
+    for (let i = 0; i < lines.length; i++) {
+        const lineRaw = lines[i];
+        if (lineRaw === undefined)
+            continue;
+        const line = lineRaw.trim();
+        // 테이블 행이 아니거나 separator면 건너뜀
+        if (!isTableRow(line))
+            continue;
+        if (isSeparatorRow(line))
+            continue;
+        // 2-column 헤더 행 확인
+        const headerCells = parseTableCells(line);
+        if (headerCells.length !== 2)
+            continue;
+        // 다음 행: separator 확인
+        const nextLine = lines[i + 1]?.trim();
+        if (!nextLine || !isSeparatorRow(nextLine))
+            continue;
+        // separator 이후 데이터 행 파싱
+        for (let j = i + 2; j < lines.length; j++) {
+            const dataLineRaw = lines[j];
+            if (dataLineRaw === undefined)
+                break;
+            const dataLine = dataLineRaw.trim();
+            if (!isTableRow(dataLine))
+                break;
+            if (isSeparatorRow(dataLine))
+                break;
+            const cells = parseTableCells(dataLine);
+            const key = cells[0];
+            const value = cells[1];
+            if (key !== undefined && key !== '' && value !== undefined && value !== '') {
+                raw[key] = value;
+            }
+        }
+        break; // 첫 번째 2-column 테이블만 파싱
+    }
+    return raw;
+}
+//# sourceMappingURL=metadata-parser.js.map

package/dist/core/parsers/pairing-question-extractor.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 페어링 질문 추출기 — Layer 1 순수 함수
+ *
+ * 계획서 마크다운에서 페어링 질문(개발자 결정 필요 항목)을 추출한다.
+ * 체크박스(`- [ ]`/`- [x]`) 형식으로 결정 여부를 파악하고,
+ * 선택된 옵션(✅ 마커)도 함께 추출한다.
+ *
+ * PRD §4.2: PairingQuestion 데이터 모델
+ *   set-unit 시 미결정 질문 목록을 표시하고, 결정된 질문은 건너뛴다.
+ *
+ * @module
+ */
+import type { PairingQuestion, PlanParsingConfig, ToolResult } from '../../types/index.js';
+/**
+ * 계획서에서 페어링 질문을 추출한다
+ *
+ * 지정된 섹션명(config.pairingQuestionSection)에 해당하는 섹션을 찾아
+ * 체크박스 기반 질문 목록을 파싱한다.
+ *
+ * 지원하는 질문 형식:
+ * - `- [ ] **Q1**: 질문 텍스트` — 미결정
+ * - `- [x] **Q2**: 결정된 질문` — 결정됨
+ * - `  - ✅Option A: 선택된 옵션` — 선택된 옵션 마커
+ *
+ * 섹션이 없거나 질문이 없으면 빈 배열 반환 (Graceful Degradation).
+ *
+ * @param content - 계획서 마크다운 전체 내용
+ * @param config - 계획서 파싱 설정 (pairingQuestionSection 사용)
+ * @returns 추출된 페어링 질문 배열을 포함한 ToolResult. 질문이 없으면 빈 배열(success: true)
+ *
+ * @example
+ * ```typescript
+ * const content = '## 페어링 질문 (결정 필요)\n\n- [x] **Q1**: 전략 선택\n  - ✅Option A: 선택됨';
+ * const config = { pairingQuestionSection: '페어링 질문' };
+ * const result = extractPairingQuestions(content, config as any);
+ * if (result.success) {
+ *   // result.data → [{ id: 'Q1', text: '전략 선택', resolved: true, selectedOption: 'Option A: 선택됨' }]
+ * }
+ * ```
+ */
+export declare function extractPairingQuestions(content: string, config: PlanParsingConfig): ToolResult<PairingQuestion[]>;
+//# sourceMappingURL=pairing-question-extractor.d.ts.map

package/dist/core/parsers/pairing-question-extractor.js

@@ -0,0 +1,146 @@
+/**
+ * 페어링 질문 추출기 — Layer 1 순수 함수
+ *
+ * 계획서 마크다운에서 페어링 질문(개발자 결정 필요 항목)을 추출한다.
+ * 체크박스(`- [ ]`/`- [x]`) 형식으로 결정 여부를 파악하고,
+ * 선택된 옵션(✅ 마커)도 함께 추출한다.
+ *
+ * PRD §4.2: PairingQuestion 데이터 모델
+ *   set-unit 시 미결정 질문 목록을 표시하고, 결정된 질문은 건너뛴다.
+ *
+ * @module
+ */
+import { ok } from '../../types/index.js';
+import { findSectionLines, normalizeLineEndings } from './md-utils.js';
+/**
+ * 질문 라인 정규식 패턴
+ *
+ * 캡처 그룹:
+ * - checked: 체크 상태 ('x', 'X', 'v', 'V', 공백 등)
+ * - id: 질문 ID (예: "Q1", "Q2", "Question 1")
+ * - text: 질문 본문
+ *
+ * 지원 형식:
+ * - `- [ ] **Q1**: 텍스트`
+ * - `- [x] **Q2**: 텍스트`
+ * - `* [v] **Q3**: 텍스트` (v 마커 지원)
+ * - `- [  ] **Q4** 텍스트` (여러 공백, 구분자 생략 지원)
+ */
+const QUESTION_LINE = /^[-*]\s+\[(?<checked>[xXvV ]*)\]\s+\*\*(?<id>[^*]+)\*\*\s*[:\-—]?\s*(?<text>.+)$/;
+/**
+ * 선택된 옵션 라인 정규식 패턴 (✅ 마커가 시작 위치)
+ *
+ * - `  - ✅Option A: 설명`
+ * - `  * ✅ Option B: 설명`
+ */
+const SELECTED_OPTION_START = /^[-*]\s+✅\s*(?<option>.+)$/;
+/**
+ * 하위 옵션 라인 정규식 패턴 (리스트 항목)
+ *
+ * 들여쓰인 모든 리스트 항목을 캡처하여 옵션 목록 구성에 사용.
+ * - `  - Option A: 설명`
+ * - `  * Option B: 설명 ✅`
+ */
+const SUB_OPTION_LINE = /^[-*]\s+(?<optionText>.+)$/;
+/**
+ * 계획서에서 페어링 질문을 추출한다
+ *
+ * 지정된 섹션명(config.pairingQuestionSection)에 해당하는 섹션을 찾아
+ * 체크박스 기반 질문 목록을 파싱한다.
+ *
+ * 지원하는 질문 형식:
+ * - `- [ ] **Q1**: 질문 텍스트` — 미결정
+ * - `- [x] **Q2**: 결정된 질문` — 결정됨
+ * - `  - ✅Option A: 선택된 옵션` — 선택된 옵션 마커
+ *
+ * 섹션이 없거나 질문이 없으면 빈 배열 반환 (Graceful Degradation).
+ *
+ * @param content - 계획서 마크다운 전체 내용
+ * @param config - 계획서 파싱 설정 (pairingQuestionSection 사용)
+ * @returns 추출된 페어링 질문 배열을 포함한 ToolResult. 질문이 없으면 빈 배열(success: true)
+ *
+ * @example
+ * ```typescript
+ * const content = '## 페어링 질문 (결정 필요)\n\n- [x] **Q1**: 전략 선택\n  - ✅Option A: 선택됨';
+ * const config = { pairingQuestionSection: '페어링 질문' };
+ * const result = extractPairingQuestions(content, config as any);
+ * if (result.success) {
+ *   // result.data → [{ id: 'Q1', text: '전략 선택', resolved: true, selectedOption: 'Option A: 선택됨' }]
+ * }
+ * ```
+ */
+export function extractPairingQuestions(content, config) {
+    const normalized = normalizeLineEndings(content);
+    const sectionLines = findSectionLines(normalized, config.pairingQuestionSection);
+    if (sectionLines.length === 0)
+        return ok([]);
+    return ok(parseQuestionLines(sectionLines));
+}
+// ── 내부 헬퍼 ──
+/**
+ * 섹션 내 라인들에서 페어링 질문을 파싱한다
+ *
+ * 상태 머신 패턴으로 라인을 순회하며:
+ * 1. 최상위 체크박스 라인 → 새 질문 시작
+ * 2. 들여쓰인 ✅ 라인 → 선택된 옵션 기록
+ *
+ * 해결되지 않은(unresolved) 질문에 ✅ 옵션이 있어도 무시한다.
+ *
+ * @param lines - 섹션 내 라인 배열
+ * @returns 파싱된 PairingQuestion 배열
+ */
+function parseQuestionLines(lines) {
+    const questions = [];
+    let current = null;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        // 최상위 리스트 항목 판별: 들여쓰기 없는 라인
+        const isTopLevel = !/^\s{2,}/.test(line);
+        if (isTopLevel) {
+            const qMatch = trimmed.match(QUESTION_LINE);
+            if (qMatch?.groups) {
+                if (current)
+                    questions.push(current);
+                const { checked, id, text } = qMatch.groups;
+                const mark = (checked ?? '').toLowerCase();
+                current = {
+                    id: (id ?? '').trim(),
+                    text: (text ?? '').trim(),
+                    resolved: mark.includes('x') || mark.includes('v'),
+                    selectedOption: undefined,
+                    options: [],
+                };
+                continue;
+            }
+        }
+        // 들여쓰인 하위 항목 — 옵션 수집 및 선택 옵션 감지
+        if (current && /^\s{2,}/.test(line)) {
+            const optMatch = trimmed.match(SUB_OPTION_LINE);
+            if (optMatch?.groups?.optionText) {
+                const rawText = optMatch.groups.optionText.trim();
+                const cleanText = rawText
+                    .replace(/^\s*✅\s*/, '')
+                    .replace(/\s*✅\s*$/, '')
+                    .trim();
+                if (!current.options)
+                    current.options = [];
+                current.options.push(cleanText);
+                if (current.resolved) {
+                    const startMatch = trimmed.match(SELECTED_OPTION_START);
+                    if (startMatch?.groups?.option) {
+                        current.selectedOption = startMatch.groups.option.replace(/\s*✅\s*$/, '').trim();
+                    }
+                    else if (rawText.endsWith('✅')) {
+                        current.selectedOption = cleanText;
+                    }
+                }
+            }
+        }
+    }
+    if (current)
+        questions.push(current);
+    return questions;
+}
+//# sourceMappingURL=pairing-question-extractor.js.map

package/dist/core/parsers/plan-parser-helpers.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 계획서 파서 내부 헬퍼 함수 — Layer 1 순수 함수
+ *
+ * @module
+ */
+import type { DepInfo, PairingQuestion, PlanParsingConfig } from '../../types/index.js';
+/**
+ * 제목을 추출하고, 실패 시 unitId로 대체한다
+ *
+ * extractTitle 결과가 undefined이거나 빈 문자열이면
+ * unitId를 제목으로 사용하고 경고를 기록한다.
+ *
+ * @param content - 마크다운 내용
+ * @param titleSource - 제목 추출 소스 설정
+ * @param unitId - 대체 제목으로 사용할 유닛 ID
+ * @param warnings - 경고 메시지를 추가할 배열 (mutated)
+ * @returns 추출된 제목 또는 unitId
+ */
+export declare function extractTitleWithFallback(content: string, titleSource: string, unitId: string, warnings: string[]): string;
+/**
+ * 메타데이터 테이블에서 phase를 추출한다
+ *
+ * phase는 선택적 필드이므로 추출 실패 시 경고 없이 undefined 반환.
+ *
+ * @param content - 마크다운 내용
+ * @param config - 파싱 설정 (metadataTable 사용)
+ * @returns phase 문자열 또는 undefined
+ */
+export declare function extractPhase(content: string, config: PlanParsingConfig): string | undefined;
+/** 의존성 추출 결과 (유닛 의존성 + 비유닛 컨텍스트 항목) */
+export interface DependencyExtractionResult {
+    depends: DepInfo[];
+    contextNotes: string[];
+}
+/**
+ * 의존성과 비유닛 컨텍스트 항목을 추출하고, 실패 시 경고를 기록한다
+ *
+ * extractDependenciesWithNotes는 내부 Fallback 체인으로 복수 전략을 시도하므로
+ * 여기서는 최종 결과만 확인한다.
+ * 결과가 빈 배열이면 경고 없음 (의존성 없는 유닛일 수 있음).
+ *
+ * @param content - 마크다운 내용
+ * @param config - 파싱 설정
+ * @param idPattern - ID 매칭 패턴 (선택)
+ * @param warnings - 경고 배열 (mutated)
+ * @returns 유닛 의존성과 비유닛 컨텍스트 항목
+ */
+export declare function extractDependsWithWarning(content: string, config: PlanParsingConfig, idPattern: string | undefined, warnings: string[]): DependencyExtractionResult;
+/**
+ * 페어링 질문을 추출하고, 실패 시 경고를 기록한다
+ *
+ * extractPairingQuestions가 실패하면 빈 배열로 대체하고 경고를 기록한다.
+ * 섹션이 없어 빈 배열이 반환되는 것은 정상 동작 (경고 없음).
+ *
+ * @param content - 마크다운 내용
+ * @param config - 파싱 설정
+ * @param warnings - 경고 배열 (mutated)
+ * @returns 추출된 페어링 질문 배열
+ */
+export declare function extractQuestionsWithWarning(content: string, config: PlanParsingConfig, warnings: string[]): PairingQuestion[];
+//# sourceMappingURL=plan-parser-helpers.d.ts.map

package/dist/core/parsers/plan-parser-helpers.js

@@ -0,0 +1,90 @@
+/**
+ * 계획서 파서 내부 헬퍼 함수 — Layer 1 순수 함수
+ *
+ * @module
+ */
+import { extractTitle } from './title-extractor.js';
+import { parseMetadataTable } from './metadata-parser.js';
+import { extractDependenciesWithNotes } from './dependency-extractor.js';
+import { extractPairingQuestions } from './pairing-question-extractor.js';
+/**
+ * 제목을 추출하고, 실패 시 unitId로 대체한다
+ *
+ * extractTitle 결과가 undefined이거나 빈 문자열이면
+ * unitId를 제목으로 사용하고 경고를 기록한다.
+ *
+ * @param content - 마크다운 내용
+ * @param titleSource - 제목 추출 소스 설정
+ * @param unitId - 대체 제목으로 사용할 유닛 ID
+ * @param warnings - 경고 메시지를 추가할 배열 (mutated)
+ * @returns 추출된 제목 또는 unitId
+ */
+export function extractTitleWithFallback(content, titleSource, unitId, warnings) {
+    const result = extractTitle(content, titleSource);
+    if (result.success && result.data !== undefined && result.data !== '') {
+        return result.data;
+    }
+    // Fallback: unitId를 제목으로 사용
+    warnings.push(`제목 추출 실패: titleSource="${titleSource}" 설정 확인. unitId를 제목으로 대체합니다.`);
+    return unitId;
+}
+/**
+ * 메타데이터 테이블에서 phase를 추출한다
+ *
+ * phase는 선택적 필드이므로 추출 실패 시 경고 없이 undefined 반환.
+ *
+ * @param content - 마크다운 내용
+ * @param config - 파싱 설정 (metadataTable 사용)
+ * @returns phase 문자열 또는 undefined
+ */
+export function extractPhase(content, config) {
+    const tableResult = parseMetadataTable(content, config.metadataTable);
+    if (tableResult.success && tableResult.data.phase !== undefined) {
+        return tableResult.data.phase;
+    }
+    // phase는 선택적 필드 — 경고 없이 undefined 반환
+    return undefined;
+}
+/**
+ * 의존성과 비유닛 컨텍스트 항목을 추출하고, 실패 시 경고를 기록한다
+ *
+ * extractDependenciesWithNotes는 내부 Fallback 체인으로 복수 전략을 시도하므로
+ * 여기서는 최종 결과만 확인한다.
+ * 결과가 빈 배열이면 경고 없음 (의존성 없는 유닛일 수 있음).
+ *
+ * @param content - 마크다운 내용
+ * @param config - 파싱 설정
+ * @param idPattern - ID 매칭 패턴 (선택)
+ * @param warnings - 경고 배열 (mutated)
+ * @returns 유닛 의존성과 비유닛 컨텍스트 항목
+ */
+export function extractDependsWithWarning(content, config, idPattern, warnings) {
+    const result = extractDependenciesWithNotes(content, config, idPattern);
+    if (result.success) {
+        return { depends: result.data.deps, contextNotes: result.data.contextNotes };
+    }
+    // 의존성 추출 실패 — 빈 결과 + 경고
+    warnings.push(`의존성 추출 실패: ${result.error.message}`);
+    return { depends: [], contextNotes: [] };
+}
+/**
+ * 페어링 질문을 추출하고, 실패 시 경고를 기록한다
+ *
+ * extractPairingQuestions가 실패하면 빈 배열로 대체하고 경고를 기록한다.
+ * 섹션이 없어 빈 배열이 반환되는 것은 정상 동작 (경고 없음).
+ *
+ * @param content - 마크다운 내용
+ * @param config - 파싱 설정
+ * @param warnings - 경고 배열 (mutated)
+ * @returns 추출된 페어링 질문 배열
+ */
+export function extractQuestionsWithWarning(content, config, warnings) {
+    const result = extractPairingQuestions(content, config);
+    if (result.success) {
+        return result.data;
+    }
+    // 페어링 질문 추출 실패 — 빈 배열 + 경고
+    warnings.push(`페어링 질문 추출 실패: ${result.error.message}`);
+    return [];
+}
+//# sourceMappingURL=plan-parser-helpers.js.map

package/dist/core/parsers/plan-parser.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 통합 계획서 파서 — Layer 1 순수 함수
+ *
+ * 개별 추출기(제목/메타데이터/의존성/페어링 질문)를 **조합**하여
+ * 계획서 마크다운을 통합 파싱한다.
+ *
+ * Core 파서의 메인 엔트리포인트로, `set-unit` 등 상위 레이어에서 호출.
+ *
+ * 부분 실패 시에도 찾은 결과를 반환하고 warnings 배열로 실패 내용을 명시한다
+ * (Graceful Degradation — PRD 원칙 3).
+ *
+ * 페어링 질문 Q1 결정: Option A (success: true + warnings 배열)
+ *
+ * @module
+ */
+import type { PairingQuestion, PlanParsingConfig, ToolResult, UnitMeta } from '../../types/index.js';
+/**
+ * parseUnitPlan 반환 타입
+ *
+ * 계획서에서 추출한 메타데이터, 페어링 질문, 경고 목록을 포함.
+ * warnings가 비어 있으면 모든 추출이 성공한 것.
+ */
+export interface ParseUnitPlanResult {
+    /** 유닛 메타데이터 (제목, phase, 의존성 등) */
+    meta: UnitMeta;
+    /** 페어링 질문 목록 (결정/미결정 모두 포함) */
+    questions: PairingQuestion[];
+    /** 부분 실패 시 경고 메시지 목록 (Graceful Degradation) */
+    warnings: string[];
+}
+/**
+ * 계획서 마크다운을 통합 파싱한다
+ *
+ * 개별 추출기를 순차적으로 호출하여 결과를 조합한다:
+ * 1. `extractTitle` → `UnitMeta.title` (실패 시 unitId로 대체)
+ * 2. `parseMetadataTable` → `UnitMeta.phase` (보조 소스)
+ * 3. `extractDependencies` → `UnitMeta.depends`
+ * 4. `extractPairingQuestions` → `questions`
+ *
+ * **Graceful Degradation** (PRD 원칙 3):
+ * - 제목 없으면 → unitId를 제목으로 사용 + 경고
+ * - 의존성 추출 실패 → 빈 배열 + 경고
+ * - 페어링 질문 추출 실패 → 빈 배열 + 경고
+ * - 빈 콘텐츠도 최소 결과를 반환
+ *
+ * `unitType`과 `planPath`는 Layer 2(Resolver)에서 채워지므로 빈 문자열로 설정.
+ *
+ * @param content - 계획서 마크다운 전체 내용
+ * @param unitId - 유닛 ID (외부에서 제공, 제목 fallback에 사용)
+ * @param parsingConfig - 계획서 파싱 설정 (titleSource, dependsSource 등)
+ * @param idPattern - 유닛 ID 매칭 정규식 패턴 (선택, extractDependencies 본문 스캔에 사용)
+ * @returns 파싱 결과(meta + questions + warnings)를 포함한 ToolResult. 항상 success: true
+ */
+export declare function parseUnitPlan(content: string, unitId: string, parsingConfig: PlanParsingConfig, idPattern?: string): ToolResult<ParseUnitPlanResult>;
+//# sourceMappingURL=plan-parser.d.ts.map

package/dist/core/parsers/plan-parser.js

@@ -0,0 +1,69 @@
+/**
+ * 통합 계획서 파서 — Layer 1 순수 함수
+ *
+ * 개별 추출기(제목/메타데이터/의존성/페어링 질문)를 **조합**하여
+ * 계획서 마크다운을 통합 파싱한다.
+ *
+ * Core 파서의 메인 엔트리포인트로, `set-unit` 등 상위 레이어에서 호출.
+ *
+ * 부분 실패 시에도 찾은 결과를 반환하고 warnings 배열로 실패 내용을 명시한다
+ * (Graceful Degradation — PRD 원칙 3).
+ *
+ * 페어링 질문 Q1 결정: Option A (success: true + warnings 배열)
+ *
+ * @module
+ */
+import { ok } from '../../types/index.js';
+import { normalizeLineEndings } from './md-utils.js';
+import { extractTitleWithFallback, extractPhase, extractDependsWithWarning, extractQuestionsWithWarning, } from './plan-parser-helpers.js';
+/**
+ * 계획서 마크다운을 통합 파싱한다
+ *
+ * 개별 추출기를 순차적으로 호출하여 결과를 조합한다:
+ * 1. `extractTitle` → `UnitMeta.title` (실패 시 unitId로 대체)
+ * 2. `parseMetadataTable` → `UnitMeta.phase` (보조 소스)
+ * 3. `extractDependencies` → `UnitMeta.depends`
+ * 4. `extractPairingQuestions` → `questions`
+ *
+ * **Graceful Degradation** (PRD 원칙 3):
+ * - 제목 없으면 → unitId를 제목으로 사용 + 경고
+ * - 의존성 추출 실패 → 빈 배열 + 경고
+ * - 페어링 질문 추출 실패 → 빈 배열 + 경고
+ * - 빈 콘텐츠도 최소 결과를 반환
+ *
+ * `unitType`과 `planPath`는 Layer 2(Resolver)에서 채워지므로 빈 문자열로 설정.
+ *
+ * @param content - 계획서 마크다운 전체 내용
+ * @param unitId - 유닛 ID (외부에서 제공, 제목 fallback에 사용)
+ * @param parsingConfig - 계획서 파싱 설정 (titleSource, dependsSource 등)
+ * @param idPattern - 유닛 ID 매칭 정규식 패턴 (선택, extractDependencies 본문 스캔에 사용)
+ * @returns 파싱 결과(meta + questions + warnings)를 포함한 ToolResult. 항상 success: true
+ */
+export function parseUnitPlan(content, unitId, parsingConfig, idPattern) {
+    const normalized = normalizeLineEndings(content);
+    const warnings = [];
+    // 1. 제목 추출 (실패 시 unitId로 대체)
+    const title = extractTitleWithFallback(normalized, parsingConfig.titleSource, unitId, warnings);
+    // 2. 메타데이터 테이블에서 phase 추출 (선택적 — 실패해도 경고 없음)
+    const phase = extractPhase(normalized, parsingConfig);
+    // 3. 의존성 추출 (Fallback 체인 적용)
+    const { depends, contextNotes } = extractDependsWithWarning(normalized, parsingConfig, idPattern, warnings);
+    // 4. 페어링 질문 추출
+    const questions = extractQuestionsWithWarning(normalized, parsingConfig, warnings);
+    // 결과 조합: unitType과 planPath는 Layer 2에서 채움
+    const meta = {
+        unitId,
+        unitType: '',
+        phase,
+        title,
+        planPath: '',
+        depends,
+        contextNotes: contextNotes.length > 0 ? contextNotes : undefined,
+    };
+    return ok({
+        meta,
+        questions,
+        warnings,
+    });
+}
+//# sourceMappingURL=plan-parser.js.map

package/dist/core/parsers/title-extractor.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 제목 추출기 — Layer 1 순수 함수
+ *
+ * 계획서 마크다운에서 제목을 추출한다.
+ * `titleSource` 설정에 따라 H1 헤더 또는 YAML frontmatter에서 가져온다.
+ *
+ * PRD §8.1 계획서 파싱:
+ *   titleSource: "h1" → 첫 번째 H1 라인에서 추출
+ *   titleSource: "frontmatter:title" → YAML frontmatter의 title 필드
+ *
+ * @module
+ */
+import type { ToolResult } from '../../types/index.js';
+/**
+ * 계획서에서 제목을 추출한다
+ *
+ * `titleSource` 설정값에 따라 추출 전략을 선택:
+ * - `"h1"`: 첫 번째 H1 헤더에서 추출
+ * - `"frontmatter:필드명"`: YAML frontmatter의 해당 필드에서 추출
+ *
+ * 못 찾으면 `undefined`를 포함한 성공 결과 반환 (에러가 아닌 부분 실패 — Graceful Degradation).
+ *
+ * @param content - 계획서 마크다운 전체 내용
+ * @param titleSource - 제목 추출 소스 설정 ("h1" | "frontmatter:title" 등)
+ * @returns 제목 문자열(또는 undefined)을 포함한 ToolResult
+ *
+ * @example
+ * ```typescript
+ * const result = extractTitle('# U-005: 제목 추출기\n\n본문', 'h1');
+ * if (result.success) {
+ *   // result.data → 'U-005: 제목 추출기'
+ * }
+ * ```
+ */
+export declare function extractTitle(content: string, titleSource: string): ToolResult<string | undefined>;
+//# sourceMappingURL=title-extractor.d.ts.map