# Parsing Specification

> Generated by openlore on 2025-01-30
> Source files: src/core/parsers/markdown-parser.ts, src/core/parsers/change-parser.ts, src/core/parsers/requirement-blocks.ts

## Purpose

Handles parsing of markdown-based specification files into structured data. Supports section-based extraction, requirement normalization, and delta block parsing for changes.

## Entities

### ParsedSection

| Property | Type | Description |
|----------|------|-------------|
| heading | string | Section heading text |
| level | number | Heading level (1-6) |
| content | string | Section body content |
| children | ParsedSection[] | Nested subsections |

### ParsedRequirement

| Property | Type | Description |
|----------|------|-------------|
| name | string | Requirement identifier |
| text | string | Full requirement text |
| scenarios | ParsedScenario[] | Associated test scenarios |
| line | number | Source line number |

### DeltaBlock

| Property | Type | Description |
|----------|------|-------------|
| operation | 'ADDED' \| 'MODIFIED' \| 'REMOVED' \| 'RENAMED' | Delta type |
| specPath | string | Target spec file path |
| content | string | Delta content |

## Requirements

### Requirement: SectionParsing

The system SHALL parse markdown files into hierarchical section structures based on heading levels.

#### Scenario: NestedHeadingExtraction
- **GIVEN** a markdown file with h1, h2, and h3 headings
- **WHEN** the file is parsed
- **THEN** sections are organized hierarchically
- **AND** h2 sections are children of h1 sections

#### Scenario: ContentExtraction
- **GIVEN** a section with paragraph text and code blocks
- **WHEN** the section is parsed
- **THEN** all content between headings is captured
- **AND** code blocks are preserved with formatting

### Requirement: RequirementExtraction

The system SHALL extract requirements from spec files following the "### Requirement:" pattern.

#### Scenario: StandardRequirementParsing
- **GIVEN** a spec with "### Requirement: UserAuth" heading
- **WHEN** requirements are extracted
- **THEN** a requirement named "UserAuth" is returned
- **AND** the requirement text includes the paragraph below the heading

#### Scenario: RequirementWithScenarios
- **GIVEN** a requirement followed by "#### Scenario:" subsections
- **WHEN** the requirement is parsed
- **THEN** all scenarios are associated with the requirement
- **AND** Given/When/Then content is captured

### Requirement: DeltaBlockParsing

The system SHALL parse delta blocks (ADDED, MODIFIED, REMOVED, RENAMED) from change spec files.

#### Scenario: AddedRequirementParsing
- **GIVEN** a change file with "## ADDED Requirements" section
- **WHEN** deltas are extracted
- **THEN** delta blocks with operation "ADDED" are returned
- **AND** the spec path and content are captured

#### Scenario: ModifiedRequirementParsing
- **GIVEN** a change file with "## MODIFIED Requirements" section
- **WHEN** deltas are extracted
- **THEN** delta blocks with operation "MODIFIED" are returned
- **AND** the full updated requirement content is included

#### Scenario: RemovedRequirementParsing
- **GIVEN** a change file with "## REMOVED Requirements" section containing "Reason:"
- **WHEN** deltas are extracted
- **THEN** delta blocks with operation "REMOVED" are returned
- **AND** the removal reason is preserved

### Requirement: GivenWhenThenExtraction

The system SHALL extract Given/When/Then scenario content with proper formatting.

#### Scenario: BoldLabelExtraction
- **GIVEN** a scenario with "- **GIVEN** user is logged in"
- **WHEN** the scenario is parsed
- **THEN** the "GIVEN" clause is extracted as "user is logged in"

#### Scenario: MultipleThens
- **GIVEN** a scenario with THEN and AND clauses
- **WHEN** the scenario is parsed
- **THEN** all outcome clauses are captured
- **AND** the AND clause is included in outcomes

### Requirement: ErrorRecovery

The system SHOULD attempt partial parsing when encountering malformed content.

#### Scenario: MalformedSectionRecovery
- **GIVEN** a spec file with one malformed section among valid sections
- **WHEN** parsing is attempted
- **THEN** valid sections are still extracted
- **AND** a warning is reported for the malformed section

## Technical Notes

- **Implementation**: `src/core/parsers/markdown-parser.ts`, `src/core/parsers/change-parser.ts`
- **Pattern**: Regex-based extraction with fallback strategies
- **Dependencies**: None (pure TypeScript implementation)