Implement ConvertFrom-Yaml with mappings, sequences, scalars, and frontmatter support

Author: MariusStorhaug

src/functions/private/ConvertFrom-YamlFrontmatter.ps1

@@ -0,0 +1,56 @@
+function ConvertFrom-YamlFrontmatter {
+    <#
+        .SYNOPSIS
+        Extracts YAML frontmatter from a string when present, otherwise returns the string unchanged.
+
+        .DESCRIPTION
+        If the input begins with a `---` line, returns the content between the opening
+        `---` and the next `---` or `...` line. Anything after the closing delimiter
+        (typically markdown body) is discarded.
+
+        If no frontmatter delimiter is detected, the original input is returned.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $Text
+    )
+
+    # Normalize line endings for matching.
+    $normalized = $Text -replace "`r`n", "`n"
+    $lines = $normalized -split "`n"
+
+    # Find first non-empty line.
+    $firstIdx = -1
+    for ($i = 0; $i -lt $lines.Count; $i++) {
+        if ($lines[$i].Trim().Length -gt 0) {
+            $firstIdx = $i
+            break
+        }
+    }
+
+    if ($firstIdx -lt 0) {
+        return $Text
+    }
+
+    if ($lines[$firstIdx].Trim() -ne '---') {
+        return $Text
+    }
+
+    # Find closing delimiter.
+    for ($j = $firstIdx + 1; $j -lt $lines.Count; $j++) {
+        $trim = $lines[$j].Trim()
+        if ($trim -eq '---' -or $trim -eq '...') {
+            $body = $lines[($firstIdx + 1)..($j - 1)] -join "`n"
+            return $body
+        }
+    }
+
+    # No closing delimiter — treat everything after opening as frontmatter.
+    if ($firstIdx + 1 -lt $lines.Count) {
+        return ($lines[($firstIdx + 1)..($lines.Count - 1)] -join "`n")
+    }
+    return ''
+}

src/functions/private/ConvertFrom-YamlLineStream.ps1

@@ -0,0 +1,98 @@
+function ConvertFrom-YamlLineStream {
+    <#
+        .SYNOPSIS
+        Splits YAML text into significant lines, dropping comments and blank lines.
+
+        .DESCRIPTION
+        Returns an array of `[pscustomobject]` records with `Indent`, `Content`, and `Number` properties.
+        - Lines that are empty or whitespace-only are skipped.
+        - Lines whose first non-whitespace character is `#` are skipped.
+        - Inline comments (` #...` outside quotes) are stripped from the content.
+        - Tabs in indentation are not allowed (YAML spec); they are treated as one space here.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Generic.List[pscustomobject]])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $Text
+    )
+
+    $result = [System.Collections.Generic.List[pscustomobject]]::new()
+    $normalized = $Text -replace "`r`n", "`n"
+    $rawLines = $normalized -split "`n"
+
+    for ($i = 0; $i -lt $rawLines.Count; $i++) {
+        $raw = $rawLines[$i]
+
+        if ([string]::IsNullOrWhiteSpace($raw)) {
+            continue
+        }
+
+        # Compute indent (spaces before first non-space).
+        $indent = 0
+        while ($indent -lt $raw.Length -and ($raw[$indent] -eq ' ' -or $raw[$indent] -eq "`t")) {
+            $indent++
+        }
+
+        $content = $raw.Substring($indent)
+
+        if ($content.StartsWith('#')) {
+            continue
+        }
+
+        # Strip inline comments while respecting single/double quotes.
+        $stripped = Remove-YamlInlineComment -Line $content
+        if ([string]::IsNullOrWhiteSpace($stripped)) {
+            continue
+        }
+
+        $result.Add([pscustomobject]@{
+                Indent  = $indent
+                Content = $stripped.TrimEnd()
+                Number  = $i + 1
+            })
+    }
+
+    return , $result
+}
+
+function Remove-YamlInlineComment {
+    <#
+        .SYNOPSIS
+        Removes an unquoted `# comment` suffix from a YAML content line.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $Line
+    )
+
+    $inSingle = $false
+    $inDouble = $false
+    for ($i = 0; $i -lt $Line.Length; $i++) {
+        $c = $Line[$i]
+        if ($c -eq '\' -and $inDouble) {
+            # Skip escaped char inside double quotes.
+            $i++
+            continue
+        }
+        if ($c -eq "'" -and -not $inDouble) {
+            $inSingle = -not $inSingle
+            continue
+        }
+        if ($c -eq '"' -and -not $inSingle) {
+            $inDouble = -not $inDouble
+            continue
+        }
+        if ($c -eq '#' -and -not $inSingle -and -not $inDouble) {
+            # Comment must be preceded by whitespace or be at start of line.
+            if ($i -eq 0 -or $Line[$i - 1] -eq ' ' -or $Line[$i - 1] -eq "`t") {
+                return $Line.Substring(0, $i)
+            }
+        }
+    }
+    return $Line
+}