test(scripts): add error and edge case tests for Generate-PrReference (#279)

## Description

Added comprehensive error path and edge case tests for
[Generate-PrReference.ps1](../../scripts/dev-tools/Generate-PrReference.ps1)
to improve test coverage. The tests verify proper error handling when
git commands fail and validate edge case behavior for empty results and
detached HEAD states.

- Added error path tests for `Test-GitAvailability`,
`Get-RepositoryRoot`, `Resolve-ComparisonReference`,
`Get-ShortCommitHash`, `Get-CommitEntry`, `Get-CommitCount`,
`Get-DiffOutput`, and `Get-DiffSummary`
- Added edge case tests for empty results in `Get-CommitCount` and
`Get-DiffSummary`
- Added `Get-CurrentBranchOrRef` tests for detached HEAD state and
unknown branch fallback scenarios
- Added `Invoke-PrReferenceGeneration` test for `ExcludeMarkdownDiff`
console output verification

## Related Issue(s)

N/A

## Type of Change

Select all that apply:

**Code & Documentation:**

- [ ] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to
change)
- [ ] Documentation update

**Infrastructure & Configuration:**

- [ ] GitHub Actions workflow
- [ ] Linting configuration (markdown, PowerShell, etc.)
- [ ] Security configuration
- [ ] DevContainer configuration
- [ ] Dependency update

**AI Artifacts:**

- [ ] Reviewed contribution with `prompt-builder` agent and addressed
all feedback
- [ ] Copilot instructions (`.github/instructions/*.instructions.md`)
- [ ] Copilot prompt (`.github/prompts/*.prompt.md`)
- [ ] Copilot agent (`.github/agents/*.agent.md`)

> **Note for AI Artifact Contributors**:
>
> - **Agents**: Research, indexing/referencing other project (using
standard VS Code GitHub Copilot/MCP tools), planning, and general
implementation agents likely already exist. Review `.github/agents/`
before creating new ones.
> - **Model Versions**: Only contributions targeting the **latest
Anthropic and OpenAI models** will be accepted. Older model versions
(e.g., GPT-3.5, Claude 3) will be rejected.
> - See [Agents Not
Accepted](../docs/contributing/custom-agents.md#agents-not-accepted) and
[Model Version
Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements).

**Other:**

- [x] Script/automation (`.ps1`, `.sh`, `.py`)
- [ ] Other (please describe):

## Sample Prompts (for AI Artifact Contributions)

N/A - This PR contains test code, not AI artifacts.

## Testing

- All 351 Pester tests pass (`npm run test:ps`)
- PSScriptAnalyzer validation passes (`npm run lint:ps`)

## Checklist

### Required Checks

- [ ] Documentation is updated (if applicable)
- [x] Files follow existing naming conventions
- [x] Changes are backwards compatible (if applicable)
- [x] Tests added for new functionality (if applicable)

### AI Artifact Contributions

N/A - No AI artifacts in this PR.

### Required Automated Checks

The following validation commands must pass before merging:

- [x] Markdown linting: `npm run lint:md`
- [x] Spell checking: `npm run spell-check`
- [x] Frontmatter validation: `npm run lint:frontmatter`
- [x] Link validation: `npm run lint:md-links`
- [x] PowerShell analysis: `npm run lint:ps`

## Security Considerations

- [x] This PR does not contain any sensitive or NDA information
- [x] Any new dependencies have been reviewed for security issues
- [x] Security-related scripts follow the principle of least privilege

## Additional Notes

This PR improves test coverage for Generate-PrReference.ps1 by adding
tests for error conditions and edge cases that were previously untested.

🧪 - Generated by Copilot

Author: WilliamBerryiii

scripts/tests/dev-tools/Generate-PrReference.Tests.ps1

@@ -9,6 +9,11 @@ Describe 'Test-GitAvailability' {
         # This test assumes git is installed in the test environment
         { Test-GitAvailability } | Should -Not -Throw
     }
+
+    It 'Should throw when git is not available' {
+        Mock Get-Command { $null } -ParameterFilter { $Name -eq 'git' }
+        { Test-GitAvailability } | Should -Throw '*Git is required*'
+    }
 }
 
 Describe 'Get-RepositoryRoot' {
@@ -22,6 +27,11 @@ Describe 'Get-RepositoryRoot' {
         $result = Get-RepositoryRoot
         Test-Path -Path (Join-Path $result '.git') | Should -BeTrue
     }
+
+    It 'Should throw when repository root cannot be determined' {
+        Mock git { $global:LASTEXITCODE = 0; return '' }
+        { Get-RepositoryRoot } | Should -Throw '*Unable to determine repository root*'
+    }
 }
 
 Describe 'New-PrDirectory' {
@@ -61,6 +71,11 @@ Describe 'Resolve-ComparisonReference' {
         $result = Resolve-ComparisonReference -BaseBranch 'main'
         $result.Ref | Should -Not -BeNullOrEmpty
     }
+
+    It 'Should throw when base branch does not exist' {
+        Mock git { $global:LASTEXITCODE = 1; return $null }
+        { Resolve-ComparisonReference -BaseBranch 'nonexistent-branch-xyz' } | Should -Throw '*does not exist*'
+    }
 }
 
 Describe 'Get-ShortCommitHash' {
@@ -74,6 +89,11 @@ Describe 'Get-ShortCommitHash' {
         $second = Get-ShortCommitHash -Ref 'HEAD'
         $first | Should -Be $second
     }
+
+    It 'Should throw when ref resolution fails' {
+        Mock git { $global:LASTEXITCODE = 128; return '' }
+        { Get-ShortCommitHash -Ref 'invalid-ref-xyz' } | Should -Throw "*Failed to resolve ref*"
+    }
 }
 
 Describe 'Get-CommitEntry' {
@@ -86,6 +106,11 @@ Describe 'Get-CommitEntry' {
         $result = Get-CommitEntry -ComparisonRef 'HEAD'
         $result | Should -BeNullOrEmpty
     }
+
+    It 'Should throw when commit history retrieval fails' {
+        Mock git { $global:LASTEXITCODE = 128; return $null }
+        { Get-CommitEntry -ComparisonRef 'main' } | Should -Throw '*Failed to retrieve commit history*'
+    }
 }
 
 Describe 'Get-CommitCount' {
@@ -100,6 +125,17 @@ Describe 'Get-CommitCount' {
         $result = Get-CommitCount -ComparisonRef 'HEAD'
         $result | Should -Be 0
     }
+
+    It 'Should throw when commit count fails' {
+        Mock git { $global:LASTEXITCODE = 128; return '' }
+        { Get-CommitCount -ComparisonRef 'main' } | Should -Throw '*Failed to count commits*'
+    }
+
+    It 'Should return 0 when commit count text is empty' {
+        Mock git { $global:LASTEXITCODE = 0; return '' }
+        $result = Get-CommitCount -ComparisonRef 'main'
+        $result | Should -Be 0
+    }
 }
 
 Describe 'Get-DiffOutput' {
@@ -113,13 +149,29 @@ Describe 'Get-DiffOutput' {
         # The result may be empty if only markdown files were changed
         { Get-DiffOutput -ComparisonRef 'HEAD~1' -ExcludeMarkdownDiff } | Should -Not -Throw
     }
+
+    It 'Should throw when diff output fails' {
+        Mock git { $global:LASTEXITCODE = 128; return $null }
+        { Get-DiffOutput -ComparisonRef 'main' } | Should -Throw '*Failed to retrieve diff output*'
+    }
 }
 
 Describe 'Get-DiffSummary' {
     It 'Returns shortstat summary string' {
         $result = Get-DiffSummary -ComparisonRef 'HEAD~1'
         $result | Should -BeOfType [string]
     }
+
+    It 'Should throw when diff summary fails' {
+        Mock git { $global:LASTEXITCODE = 128; return $null }
+        { Get-DiffSummary -ComparisonRef 'main' } | Should -Throw '*Failed to summarize diff output*'
+    }
+
+    It 'Should return "0 files changed" when diff summary is empty' {
+        Mock git { $global:LASTEXITCODE = 0; return '' }
+        $result = Get-DiffSummary -ComparisonRef 'main'
+        $result | Should -Be '0 files changed'
+    }
 }
 
 Describe 'Get-PrXmlContent' {
@@ -191,6 +243,33 @@ Describe 'Get-CurrentBranchOrRef' {
         # Either a branch name or detached@<sha>
         ($result -match '^detached@' -or $result -notmatch '^detached@') | Should -BeTrue
     }
+
+    It 'Should return detached@sha when in detached HEAD state' {
+        # Use call sequence to distinguish git commands (cross-platform safe)
+        $script:gitCallCount = 0
+        Mock git {
+            $script:gitCallCount++
+            if ($script:gitCallCount -eq 1) {
+                # First call: git branch --show-current returns empty (detached)
+                $global:LASTEXITCODE = 0
+                return ''
+            }
+            # Second call: git rev-parse --short HEAD returns SHA
+            $global:LASTEXITCODE = 0
+            return 'abc1234'
+        }
+        $result = Get-CurrentBranchOrRef
+        $result | Should -Be 'detached@abc1234'
+    }
+
+    It 'Should return unknown when both branch and rev-parse fail' {
+        Mock git {
+            $global:LASTEXITCODE = 128
+            return $null
+        }
+        $result = Get-CurrentBranchOrRef
+        $result | Should -Be 'unknown'
+    }
 }
 
 Describe 'Invoke-PrReferenceGeneration' {
@@ -221,4 +300,35 @@ Describe 'Invoke-PrReferenceGeneration' {
         $result | Should -BeOfType [System.IO.FileInfo]
         $result.Extension | Should -Be '.xml'
     }
+
+    It 'Should include markdown exclusion note when ExcludeMarkdownDiff is specified' {
+        # Skip if not in a git repo or no commits
+        $commitCount = Get-CommitCount -ComparisonRef 'HEAD~1'
+        if ($commitCount -eq 0) {
+            Set-ItResult -Skipped -Because 'No commits available for comparison'
+            return
+        }
+
+        $baseBranch = $null
+        foreach ($candidate in @('origin/main', 'main', 'HEAD~1')) {
+            & git rev-parse --verify $candidate 2>$null | Out-Null
+            if ($LASTEXITCODE -eq 0) {
+                $baseBranch = $candidate
+                break
+            }
+        }
+
+        if (-not $baseBranch) {
+            Set-ItResult -Skipped -Because 'No suitable base branch available for comparison'
+            return
+        }
+
+        Mock Write-Host {}
+
+        $result = Invoke-PrReferenceGeneration -BaseBranch $baseBranch -ExcludeMarkdownDiff
+        $result | Should -BeOfType [System.IO.FileInfo]
+
+        # Verify the markdown exclusion note was output
+        Should -Invoke Write-Host -ParameterFilter { $Object -eq 'Note: Markdown files were excluded from diff output' }
+    }
 }