From 8202fe6cc596d5388e190e90785503565071afb4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 27 Aug 2025 11:44:08 +0000 Subject: [PATCH 1/2] Initial plan From 26fac4aa44672994962762c67875fc1431b05442 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 27 Aug 2025 11:53:41 +0000 Subject: [PATCH 2/2] Create comprehensive GitHub Copilot instructions for PSModule/Dns repository Co-authored-by: MariusStorhaug <17722253+MariusStorhaug@users.noreply.github.com> --- .github/copilot-instructions.md | 166 ++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..22d2856 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,166 @@ +# PSModule/Dns PowerShell Module + +The Dns module provides PowerShell functions for DNS resolution operations using the System.Net.Dns class. + +**ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.** + +## Working Effectively + +### Prerequisites +- PowerShell 7.4.11+ is pre-installed +- Pester 5.7.1 is pre-installed for testing +- PSScriptAnalyzer 1.24.0 is pre-installed for linting + +### Development Workflow +**CRITICAL**: This is a pure PowerShell module with NO build compilation required. + +1. **Load the module for testing** (takes <1 second): + ```powershell + cd /home/runner/work/Dns/Dns + . ./src/classes/public/DnsHost.ps1 + . ./src/functions/public/Resolve-DnsHost.ps1 + ``` + +2. **Run tests** (takes ~2 seconds): + ```powershell + # Define LogGroup function required by tests + function LogGroup { + param([string]$Title, [scriptblock]$ScriptBlock) + Write-Host "::group::$Title" + try { & $ScriptBlock } finally { Write-Host '::endgroup::' } + } + + # Load module first + . ./src/classes/public/DnsHost.ps1 + . ./src/functions/public/Resolve-DnsHost.ps1 + + # Run Pester tests + Invoke-Pester ./tests/Dns.Tests.ps1 -Passthru + ``` + +3. **Run linting** (takes ~1.3 seconds): + ```powershell + # Lint source code + Invoke-ScriptAnalyzer -Path ./src -Recurse -Settings ./.github/linters/.powershell-psscriptanalyzer.psd1 + + # Lint tests + Invoke-ScriptAnalyzer -Path ./tests -Recurse -Settings ./.github/linters/.powershell-psscriptanalyzer.psd1 + ``` + +### Manual Validation Scenarios +**ALWAYS run these validation steps after making any changes to ensure functionality works correctly:** + +```powershell +# Load the module +. ./src/classes/public/DnsHost.ps1 +. ./src/functions/public/Resolve-DnsHost.ps1 + +# Test 1: DnsHost class construction +$dnsHost = [DnsHost]::new('test.example.com', 'test', @('192.168.1.1', '192.168.1.2')) +$dnsHost | Format-List # Should show Name, Alias, AddressList properties + +# Test 2: DNS resolution with localhost (WORKS in sandbox) +$result = Resolve-DnsHost -Name '127.0.0.1' +if ($result) { + Write-Host 'SUCCESS: DNS resolution works!' + $result | Format-List # Should show localhost with 127.0.0.1 +} else { + Write-Host 'FAILED: DNS resolution returned null' +} + +# Test 3: Invalid domain handling +$result = Resolve-DnsHost -Name 'nonexistent.invalid.domain.test' +if ($result) { + Write-Host 'UNEXPECTED: Should have returned null' +} else { + Write-Host 'SUCCESS: Invalid domain correctly returned null' +} +``` + +## Important Limitations and Workarounds + +### Network Restrictions +- **CRITICAL**: External DNS resolution (google.com, example.com) FAILS in sandbox environment +- **WORKAROUND**: Use localhost/127.0.0.1 for testing DNS functionality +- **CI BEHAVIOR**: The PSModule framework CI runs in environments with full network access +- Tests that require external DNS will fail locally but pass in CI + +### PSModule Framework +- This module uses the [PSModule framework](https://github.com/PSModule/Process-PSModule) for CI/CD +- The framework handles module building, testing, and publishing automatically +- **NO local build steps required** - the module is pure PowerShell scripts +- CI workflows are in `.github/workflows/Process-PSModule.yml` using PSModule/Process-PSModule@v4 + +## Repository Structure + +### Source Code +``` +src/ +├── classes/public/DnsHost.ps1 # DnsHost class definition +└── functions/public/Resolve-DnsHost.ps1 # Main DNS resolution function +``` + +### Tests +``` +tests/Dns.Tests.ps1 # Pester tests (requires Pester 5.7.1) +``` + +### Configuration +``` +.github/linters/.powershell-psscriptanalyzer.psd1 # PSScriptAnalyzer rules +.github/PSModule.yml # PSModule framework configuration +.github/workflows/Process-PSModule.yml # Main CI/CD workflow +.github/workflows/Linter.yml # Super-linter workflow +``` + +## Common Tasks + +### Adding New Functions +1. Create new function file in `src/functions/public/` +2. Follow existing pattern with proper comment-based help +3. Add corresponding tests in `tests/Dns.Tests.ps1` +4. Run validation steps to ensure functionality works + +### Modifying Existing Code +1. **ALWAYS load and test manually first** using the validation scenarios above +2. Run linting: `Invoke-ScriptAnalyzer -Path ./src -Recurse -Settings ./.github/linters/.powershell-psscriptanalyzer.psd1` +3. Run tests: Load module then `Invoke-Pester ./tests/Dns.Tests.ps1 -Passthru` +4. **CRITICAL**: External DNS tests will fail locally but pass in CI + +### Understanding Test Failures +- Tests expecting external DNS resolution will fail in sandbox environment +- Example: Tests for 'google.com' and 'example.com' fail locally +- Tests for 'nonexistent.example' pass (expects null result) +- **This is expected behavior** - the CI environment has full network access + +## Key Module Components + +### DnsHost Class +- Properties: `Name` (string), `Alias` (string), `AddressList` (string[]) +- Constructor: `[DnsHost]::new($name, $alias, $addressList)` +- Used to return structured DNS resolution results + +### Resolve-DnsHost Function +- **Purpose**: Resolves hostnames to IP addresses using System.Net.Dns +- **Parameters**: + - `Name` (mandatory) - hostname to resolve + - `AddressFamily` (optional) - defaults to 'Unspecified' +- **Returns**: `[DnsHost]` object or `$null` if resolution fails +- **Error Handling**: Catches exceptions and writes debug output + +### Validation Checklist +When making changes, ALWAYS verify: +- [ ] PSScriptAnalyzer passes with zero issues +- [ ] Module loads without errors +- [ ] DnsHost class constructs correctly +- [ ] Resolve-DnsHost works with localhost (127.0.0.1) +- [ ] Invalid domain names return null appropriately +- [ ] Pester tests run (external DNS failures expected locally) + +## Time Expectations +- Module loading: <1 second +- PSScriptAnalyzer linting: ~1.3 seconds +- Pester test execution: ~2 seconds (including expected failures) +- Manual validation scenarios: <5 seconds total + +**NEVER set timeouts less than 30 seconds for any PowerShell operations to account for potential module initialization overhead.** \ No newline at end of file