Implement YAML parsing for requirements documents

[Copilot]

Implements parsing of requirements YAML files as specified in README.md format, including hierarchical sections, test mappings, and file includes.

Implementation

• Data Model: Requirement, Section, and Requirements classes form a DOM tree for requirements hierarchy
• Parser: Static Requirements.Read(params string[] paths) method using YamlDotNet with hyphenated naming convention
  • Supports reading single or multiple files in one call
  • Automatically merges sections with identical titles across files
  • Validates that at least one file path is provided
• Include Resolution: Handles file includes with circular reference detection via _includedFiles tracking
• Section Merging: Merges sections with identical titles across files and within includes
• Test Mappings: Supports inline tests and separate mappings via mappings section
• Validation: Comprehensive validation with detailed error messages including:
  • Blank requirement IDs (with section title and file path)
  • Blank requirement titles (with requirement ID and file path)
  • Blank section titles (with file path)
  • Blank test names in requirements (with requirement ID and file path)
  • Blank test names in mappings (with mapping ID and file path)
  • Blank mapping requirement IDs (with file path)
  • Duplicate requirement IDs across all files (with requirement ID and file path)

All validation errors throw InvalidOperationException with file location information to help users quickly identify and fix issues.

Usage

// Parse a single requirements file
var requirements = Requirements.Read("system_requirements.yaml");

// Parse multiple requirements files in one call
var requirements = Requirements.Read("security.yaml", "performance.yaml", "data.yaml");

// Navigate the hierarchy
foreach (var section in requirements.Sections)
{
    foreach (var req in section.Requirements)
    {
        Console.WriteLine($"{req.Id}: {req.Title}");
        Console.WriteLine($"  Tests: {string.Join(", ", req.Tests)}");
    }
}

Testing

26 unit tests covering:

• Simple and nested structures
• File includes and section merging
• Test mappings (inline and separate)
• Error conditions (duplicate IDs, missing files, circular includes)
• Validation failures (blank IDs, titles, section titles, test names) with file location verification
• Multiple file scenarios (merging, section combining, duplicate detection across files)
• Backwards compatibility with single file usage

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature]: Implement Requirements YAML parsing</issue_title>
<issue_description>### Problem Statement

There is no code to read the requirements YAML file format specified in the README.md file

Proposed Solution

Implement the code to read requirements. The approach should:

• Use YamlDotNet as the YAML reader (and note this in the AGENTS.md as a technology dependency
• Create a Requirement class which holds the information for a requirement (id, title, tests, child-ids)
• Create a Section class which holds the contents of a section (requirements and child sections)
• Create a Requirements class which holds the entire requirements DOM tree (might inherit from Section)
• Implement a Read(string path) method which reads a requirements YAML file - including resolving other includes
• The read function should fail on duplicate requirement IDs
• Consider making the Read function safe from getting stuck in an include-loop by having the Requirements class remember all files it's included and skipping already-included files

Note that unit tests should be implemented which:

• Create test YAML files in a temporary folder
• Read the YAML files into a Requirements class
• Verify the files were read correctly, or throw appropriate failures if corrupt or invalid

Alternatives Considered

No response

Additional Context

No response

Priority

High - Blocking current work

Contribution

• I would be willing to submit a PR for this feature

Code of Conduct

• I agree to follow this project's Code of Conduct</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Feature]: Implement Requirements YAML parsing #15

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Malcolmnixon]

@copilot The reader logic should throw exceptions (with file and location information in the text) for errors such as blank requirement-IDs, requirement-titles, section-titles, or test-names. These failure scenarios should be tested.

[Copilot]

@copilot The reader logic should throw exceptions (with file and location information in the text) for errors such as blank requirement-IDs, requirement-titles, section-titles, or test-names. These fa...

Added validation for all blank field scenarios with file location information in error messages (commit a1b4eed).

The parser now validates and throws InvalidOperationException for:

• Blank requirement IDs (includes section title and file path)
• Blank requirement titles (includes requirement ID and file path)
• Blank section titles (includes file path)
• Blank test names in requirements (includes requirement ID and file path)
• Blank test names in mappings (includes mapping ID and file path)
• Blank mapping requirement IDs (includes file path)
• Duplicate requirement IDs (includes requirement ID and file path)

All 7 validation scenarios have corresponding unit tests that verify the error messages contain the appropriate context and file location information.

[Malcolmnixon]

@copilot Consider enhancing the Requirements static Read method so it can take a params array of files - allowing the caller to pass in one file or multiple. This too should have appropriate tests.

[Copilot]

@copilot Consider enhancing the Requirements static Read method so it can take a params array of files - allowing the caller to pass in one file or multiple. This too should have appropriate tests.

Enhanced the Requirements.Read() method to accept a params array of file paths (commit 5887da7).

The method now supports:

• Single file: Requirements.Read("file.yaml")
• Multiple files: Requirements.Read("file1.yaml", "file2.yaml", "file3.yaml")
• Automatic section merging across files
• Duplicate ID detection across all files
• Validation that at least one path is provided

Added 6 new tests covering all scenarios including merging multiple files, section merging, backwards compatibility, validation, and duplicate detection across files.