[pull] master from microsoft:master

Tools/PRTest.ps1

@@ -1,11 +1,22 @@
-# This script does a checkout of a Pull Request using the GitHub CLI, and then runs it using SandboxTest.ps1.
+### Exit Codes:
+#  0 = Success
+#  1 = Missing dependency
+#  2 = Pull request checkout error
+#  3 = Validation completed check was not found
+#  4 = Artifact download URL was not found
+#  5 = YAML manifest was not found
+###
+
+# This script checks out a Pull Request or downloads its validated merged manifest,
+# and then runs it using SandboxTest.ps1.
 
 Param(
-    [Parameter(Position = 0, HelpMessage = 'The Pull Request to checkout.', Mandatory = $true)]
+    [Parameter(Position = 0, HelpMessage = 'The Pull Request to test.', Mandatory = $true)]
     [String] $PullRequest,
     [Parameter(HelpMessage = "Open the Pull Request's review page in the default browser")]
     [Switch] $Review = $false,
     [Switch] $KeepBranch = $false,
+    [Switch] $NoCheckout = $false,
     [Switch] $Prerelease = $false,
     [Switch] $EnableExperimentalFeatures = $false,
     [string] $WinGetVersion = $null,
@@ -23,6 +34,18 @@ filter Initialize-VirtualTerminalSequence {
     }
 }
 
+function Write-PRTestError {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $Message,
+        [Parameter(Mandatory = $true)]
+        [int] $ExitCode
+    )
+
+    Write-Error -Message $Message -ErrorAction Continue
+    exit $ExitCode
+}
+
 # Flags
 Write-Debug 'Checking for supported features'
 $script:vtSupported = (Get-Host).UI.SupportsVirtualTerminal
@@ -37,21 +60,86 @@ $script:vtForegroundGreen = 32 | Initialize-VirtualTerminalSequence
 Write-Debug 'Creating internal state'
 $PullRequest = $PullRequest.TrimStart('#')
 $ErrorActionPreference = 'Stop'
-$repositoryRoot = 'https://github.com/microsoft/winget-pkgs/'
-$rootDirectory = ((Resolve-Path (git rev-parse --show-toplevel)).ToString() + '\')
+$repository = 'microsoft/winget-pkgs'
 
 Write-Verbose 'Ensuring Dependencies are Present'
-if (!$script:GhIsPresent) { Write-Error "The GitHub CLI is not installed. Install it via 'winget install GitHub.cli' and come back here!" -ErrorAction Stop }
-if (!$script:GitIsPresent) { Write-Error "Git is not installed. Install it via 'winget install Git.Git' and come back here!" -ErrorAction Stop }
-if (!$script:SandboxIsPresent) { Write-Error 'Windows Sandbox is not enabled. Enable it and come back here!' -ErrorAction Stop }
+if (!$script:GhIsPresent) { Write-PRTestError "The GitHub CLI is not installed. Install it via 'winget install GitHub.cli' and come back here!" 1 }
+if (!$NoCheckout -and !$script:GitIsPresent) { Write-PRTestError "Git is not installed. Install it via 'winget install Git.Git' and come back here!" 1 }
+if (!$script:SandboxIsPresent) { Write-PRTestError 'Windows Sandbox is not enabled. Enable it and come back here!' 1 }
+
+if ($NoCheckout) {
+    $rootFolder = Join-Path $env:TEMP 'WinGet-PRTest'
+    if ($Clean -and (Test-Path $rootFolder)) { Remove-Item $rootFolder -Recurse -Force }
+
+    Write-Output '--> Retrieving PR check runs'
+    $headSha = gh api "repos/$repository/pulls/$PullRequest" --jq '.head.sha'
+    $checkRuns = gh api "repos/$repository/commits/$headSha/check-runs?app_id=1451866&filter=latest&per_page=100" |
+        ConvertFrom-Json -ErrorAction SilentlyContinue
+    $validationCompletedCheck = $checkRuns.check_runs |
+        Where-Object {
+            $_.name -eq '10. Validation Completed' -and
+            $_.app.slug -eq 'wingetvalidator-prod' -and
+            $_.head_sha -eq $headSha -and
+            $_.status -eq 'completed'
+        } |
+        Select-Object -First 1
+
+    if (!$validationCompletedCheck) {
+        Write-PRTestError "The check run was not found for PR #$PullRequest." 3
+    }
+
+    $json = [regex]::Match(
+        [string] $validationCompletedCheck.output.text,
+        '(?ms)```json\s*(?<json>.*?)\s*```'
+    ).Groups['json'].Value
+    $artifactDownloadUrl = ($json | ConvertFrom-Json -ErrorAction SilentlyContinue).Artifacts.ArtifactDownloadUrl
+    if ([string]::IsNullOrWhiteSpace($artifactDownloadUrl)) {
+        Write-PRTestError "The artifact download URL was not found for PR #$PullRequest." 4
+    }
 
-Write-Verbose 'Checking out PR'
-gh pr checkout $PullRequest $(if (!$KeepBranch) { '--detach' }) -f -R $repositoryRoot | Out-Null
-if ($LASTEXITCODE -ne 0) { Write-Error "There was an error checking out the PR. Make sure you're logged into GitHub via 'gh auth login' and come back here!" -ErrorAction Stop }
+    $runFolder = Join-Path $rootFolder "$PullRequest\$headSha"
+    $zipPath = Join-Path $runFolder 'artifacts.zip'
+    $manifestFolder = Join-Path $runFolder 'Manifest'
+    if (Test-Path $runFolder) { Remove-Item $runFolder -Recurse -Force }
+    New-Item $manifestFolder -ItemType Directory | Out-Null
 
-Write-Verbose 'Parsing changed files'
-$manifest = @(gh pr diff $PullRequest --name-only)
-$path = (Get-Item (Resolve-Path ($rootDirectory + $manifest[0]))).Directory
+    Write-Output '--> Downloading validation artifact'
+    Invoke-WebRequest $artifactDownloadUrl -OutFile $zipPath
+
+    # Only extract the YAML manifest entry from the archive; the artifact also contains
+    # installation verification logs whose long, nested paths can fail to extract.
+    $manifestFile = $null
+    try {
+        $zipArchive = [System.IO.Compression.ZipFile]::OpenRead($zipPath)
+        $yamlEntries = @($zipArchive.Entries | Where-Object { $_.Name -like '*.yaml' })
+        if ($yamlEntries.Count -eq 1) {
+            Write-Output "--> Extracting file: $($yamlEntries[0].Name)"
+            $manifestFile = Join-Path $manifestFolder $yamlEntries[0].Name
+            [System.IO.Compression.ZipFileExtensions]::ExtractToFile($yamlEntries[0], $manifestFile)
+        }
+    } finally {
+        if ($zipArchive) { $zipArchive.Dispose() }
+    }
+
+    if (!$manifestFile -or !(Test-Path $manifestFile -PathType Leaf)) {
+        Write-PRTestError "A single YAML manifest was not found in the validation artifact for PR #$PullRequest." 5
+    }
+
+    $path = $manifestFolder
+} else {
+    $repositoryRoot = 'https://github.com/microsoft/winget-pkgs/'
+    $rootDirectory = ((Resolve-Path (git rev-parse --show-toplevel)).ToString() + '\')
+
+    Write-Verbose 'Checking out PR'
+    gh pr checkout $PullRequest $(if (!$KeepBranch) { '--detach' }) -f -R $repositoryRoot | Out-Null
+    if ($LASTEXITCODE -ne 0) {
+        Write-PRTestError "There was an error checking out the PR. Make sure you're logged into GitHub via 'gh auth login' and come back here!" 2
+    }
+
+    Write-Verbose 'Parsing changed files'
+    $manifest = @(gh pr diff $PullRequest --name-only)
+    $path = (Get-Item (Resolve-Path ($rootDirectory + $manifest[0]))).Directory
+}
 
 Write-Verbose 'Passing execution to SandboxTest.ps1'
 $sandboxTestPath = (Resolve-Path ($PSScriptRoot.ToString() + '\SandboxTest.ps1')).ToString()

doc/Moderation.md

@@ -51,7 +51,13 @@ Sometimes contributors may request assistance from moderators in order to take a
 
 Before requesting assistance, please work through these recommendations first:
 
-1. Wait. Sometimes moderators are busy or working on pressing matters. If you're an infrequent contributor, your pull request is subject to greater scrutiny than frequent contributors. Please be patient, but reach out if your pull request is outstanding for more than 24 hours.
+1. **Please be patient.** Moderators may be busy or working on pressing matters. They generally prioritize the oldest open pull requests that have completed validation and are otherwise ready for moderator review. A pull request's exact position may vary because different submissions require different levels of scrutiny:
+
+   - [**New versions ready for moderator review, oldest first**](https://github.com/microsoft/winget-pkgs/pulls?q=is%3Apr+is%3Aopen+label%3ANew-Manifest+label%3AValidation-Completed+-label%3ANew-Package+-label%3ANeeds-Author-Feedback+-label%3ANeeds-Attention+-label%3ABlocking-Issue+-label%3ANeeds-CLA+-label%3AChanges-Requested+-label%3AModerator-Approved+sort%3Acreated-asc): Updates to established packages may require less scrutiny when prior manifests provide clear precedent for the package identity, installer source, and metadata.
+   - [**New packages ready for moderator review, oldest first**](https://github.com/microsoft/winget-pkgs/pulls?q=is%3Apr+is%3Aopen+label%3ANew-Package+label%3AValidation-Completed+-label%3ANeeds-Author-Feedback+-label%3ANeeds-Attention+-label%3ABlocking-Issue+-label%3ANeeds-CLA+-label%3AChanges-Requested+-label%3AModerator-Approved+sort%3Acreated-asc): New packages generally require more scrutiny because moderators must establish package identity, installer provenance, metadata accuracy, and policy compliance without prior manifest history.
+   - [**Pull requests awaiting author feedback, oldest first**](https://github.com/microsoft/winget-pkgs/pulls?q=is%3Apr+is%3Aopen+label%3ANeeds-Author-Feedback+sort%3Acreated-asc): These pull requests are not currently waiting on moderator approval. Review the comments and validation labels, make the requested changes, and respond when the pull request is ready for another review.
+
+   These lists can help you understand the approximate position and state of your pull request, but they are not strict queues. Validation results, security or policy concerns, package complexity, and contributor responses may change the order in which pull requests are reviewed.
 2. If you've submitted a pull request and it hasn't been approved, review any comments and labels to ensure no action or information is outstanding from you.
 3. If you're helping on an existing package (new version, change, etc), consider contacting any regular package maintainer and ask for their assistance. They may be able to help vouch for your issue/pull request or help explain why it's stuck.
 
@@ -63,6 +69,9 @@ In spite of the above, if the issue or pull request is urgent (i.e. critical sec
 
 For infrequent contributors, GitHub @mentions are likely the easiest way to get attention. As there are many moderators in the project, the best way to know who to tag is to check [recently closed pull requests](https://github.com/microsoft/winget-pkgs/pulls?q=is%3Apr+is%3Aclosed+label%3AModerator-Approved) and see which moderator(s) have closed recent pull requests. This is a generally indicative of which moderator(s) are active and able to assist.
 
+> [!NOTE]
+> Community moderators can assist with standard manifest reviews, but pull requests with a red `Policy-*`, `Validation-Domain`, or `Validation-Executable-Error` label require review by a Windows Package Manager administrator. Mentioning a community moderator will not advance an administrator-only review. The current administrators are listed at the top of this document.
+
 Please ensure when you mention a moderator to include a clear and concise note of what action you are requesting. Please only mention a maximum of two moderators at a time to prevent miscommunications.
 
 ### Matrix Room

doc/ValidationFailureGuide.md

@@ -46,6 +46,9 @@ These labels track the progress of your PR through the validation pipeline.
 
 ## Error Labels
 
+> [!IMPORTANT]
+> Pull requests with a red `Policy-*`, `Validation-Domain`, or `Validation-Executable-Error` label require review by a Windows Package Manager administrator. Community moderator approval alone cannot resolve or waive these labels. Review any validation details and requested changes first; if the label remains after those issues are addressed, the pull request must wait for administrator review.
+
 ### Manifest & Path Errors
 
 #### `Manifest-Validation-Error`
@@ -140,6 +143,9 @@ manifests/<first-letter>/<Publisher>/<PackageName>/<PackageVersion>/
 2. If flagged as malware/PUA, [submit the installer to Microsoft Defender for analysis](https://www.microsoft.com/wdsi/filesubmission) as a potential false positive.
 3. Ensure the installer URL is publicly accessible.
 
+> [!CAUTION]
+> ESRP scan blocking detections result in the `Binary-Validation-Error` label. This label cannot be waived by a moderator or administrator. Future handling for PUA detections is being evaluated for [PUA broadly](https://github.com/microsoft/winget-cli/issues/6189), [remote-access tools](https://github.com/microsoft/winget-cli/issues/6107), and [encrypted-file detections](https://github.com/microsoft/winget-cli/issues/6250), but these proposals do not currently provide an exception. The detected issue must be resolved—for example, by correcting or replacing the installer, or by having an incorrect detection cleared—before the pull request can pass a new validation run.
+
 ---
 
 #### `Error-Hash-Mismatch`
@@ -216,7 +222,7 @@ Update the `InstallerSha256` value in your manifest and resubmit.
 - Using a third-party CDN, mirror, or download aggregator instead of the official publisher URL
 - Using a URL shortener or redirector
 
-**How to fix:** Use the official download URL from the publisher's website. If the URL is legitimate, add a comment to your PR for investigation.
+**How to fix:** Use the official download URL from the publisher's website. If the flagged domain is legitimate, add a comment with publisher-controlled evidence showing how the package or download page leads to the installer URL. A Windows Package Manager administrator must review that evidence and determine whether the domain can be approved or waived; community moderators cannot make that decision.
 
 > [!TIP]
 > Including `PackageUrl` in your manifest and ensuring the `InstallerUrl` can be found by navigating the publisher's website from that URL helps speed up moderator reviews.
@@ -302,14 +308,16 @@ Function Get-UrlResponse {
 
 #### `Validation-Executable-Error`
 
-**What it means:** After installation, the test could not locate the primary application executable.
+**What it means:** Post-install validation could not successfully locate or run an expected application executable, or the executable returned an unexpected result.
 
 **Common causes:**
-- The application installs to a non-standard location
-- The application is a service or background process without a visible executable
-- Installation did not complete successfully
+- The application installs to a non-standard location.
+- A command-line application requires an argument such as `--version` to exit successfully.
+- The executable requires a dependency that is unavailable in the validation environment.
+- The application is a service or background process without a suitable executable.
+- Installation did not complete successfully.
 
-**How to fix:** Ensure the application installs correctly and its main executable is discoverable. If the app is not a traditional desktop application, add a comment to the PR for engineer investigation.
+**How to fix:** Review the validation details and confirm that the application installs and runs correctly. If a command-line executable requires a specific argument, include the executable name and argument in a PR comment so a Windows Package Manager administrator can add the installation metadata. Any remaining `Validation-Executable-Error` requires administrator review; community moderators cannot resolve or waive it.
 
 ---
 
@@ -409,7 +417,9 @@ Function Get-UrlResponse {
 
 ## Content Policy Labels
 
-These labels indicate that something in your manifest metadata triggered a content policy review. Your PR will undergo additional manual review.
+These labels indicate that manifest metadata triggered a content policy review. False positives can occur when a word or phrase is interpreted without its surrounding context. Open the `10. Validation Completed` check and review its artifacts to find the flagged word or phrase.
+
+Red `Policy-*` labels require review by a Windows Package Manager administrator; community moderator approval alone cannot resolve or waive them. Review the referenced policy and correct the metadata if necessary. When possible, you may resolve a false positive by accurately rewording the metadata—for example, replacing "explicit approval instructions" with "direct approval instructions." Do not omit or alter relevant facts merely to avoid a policy match. If no accurate correction is appropriate, the pull request must wait for administrator review.
 
 | Label | Policy |
 |---|---|
@@ -468,23 +478,23 @@ These labels are applied by [moderators](https://github.com/microsoft/winget-pkg
 
 ## Quick Reference Table
 
-| Label | Category | Author Action Required? | Summary |
+| Label | Category | Author Action / Review | Summary |
 |---|---|---|---|
 | `Manifest-Validation-Error` | Manifest | ✅ Yes | Fix YAML syntax / schema errors |
 | `Manifest-Version-Deprecated` | Manifest | ✅ Yes | Update to a supported schema version |
 | `Manifest-Path-Error` | Manifest | ✅ Yes | Fix directory structure / file naming |
 | `PullRequest-Error` | PR | ✅ Yes | One package, one version per PR |
 | `Manifest-Installer-Validation-Error` | Manifest | ✅ Yes | Fix installer metadata inconsistencies |
-| `Binary-Validation-Error` | Installer | ✅ Yes | Fix AV detection or hash/URL issues |
+| `Binary-Validation-Error` | Installer | ✅ Yes | Resolve ESRP detection or installer issue; this label cannot be waived |
 | `Error-Hash-Mismatch` | Installer | ✅ Yes | Update `InstallerSha256` |
 | `Error-Installer-Availability` | Installer | ✅ Yes | Fix installer URL |
 | `URL-Validation-Error` | URL | ✅ Yes | Fix broken or untrusted URLs |
 | `Validation-HTTP-Error` | URL | ✅ Yes | Switch to HTTPS |
-| `Validation-Domain` | URL | ⚠️ Maybe | Use publisher's official URL |
+| `Validation-Domain` | URL | 🔒 Administrator review | Use publisher's official URL or provide publisher-controlled evidence |
 | `Validation-Unapproved-URL` | URL | ⚠️ Maybe | Use approved publisher URL |
 | `Validation-Indirect-URL` | URL | ✅ Yes | Remove URL redirection |
 | `Validation-Unattended-Failed` | Install | ✅ Yes | Fix silent install switches |
-| `Validation-Executable-Error` | Install | ⚠️ Maybe | Verify executable is discoverable |
+| `Validation-Executable-Error` | Install | 🔒 Administrator review | Verify the executable runs successfully and provide any required argument |
 | `Validation-Installation-Error` | Install | ✅ Yes | Fix installation failure (check elevation) |
 | `Validation-Shell-Execute` | Install | ✅ Yes | Fix installer launch failure (check elevation) |
 | `Validation-Defender-Error` | Install | ⚠️ Maybe | Fix or submit for false positive review |
@@ -493,14 +503,14 @@ These labels are applied by [moderators](https://github.com/microsoft/winget-pkg
 | `Validation-VCRuntime-Dependency` | Dependency | ✅ Yes | Add VC++ runtime dependency |
 | `Needs-CLA` | PR | ✅ Yes | Sign the Contributor License Agreement |
 | `Internal-Error-*` | Internal | ❌ No | WinGet team will investigate |
-| `Policy-Test-*` | Content | ⚠️ Maybe | Additional manual review required |
+| `Policy-Test-*` | Content | 🔒 Administrator review | Review the policy and correct the metadata if necessary |
 
 ---
 
 ## Getting Help
 
 - **Re-run validation:** A moderator can comment `@wingetbot run` on your PR to re-trigger the validation pipeline.
-- **Ask a moderator:** Check [recently closed PRs](https://github.com/microsoft/winget-pkgs/pulls?q=is%3Apr+is%3Aclosed+label%3AModerator-Approved) to find an active moderator and `@mention` them.
+- **Request review:** See the [moderation guidance](Moderation.md) to understand the review queues and determine whether your pull request needs a community moderator or a Windows Package Manager administrator. Before mentioning anyone, confirm that validation has completed and that no author action is outstanding.
 - **File an issue:** If you believe the failure is incorrect, [open an issue](https://github.com/microsoft/winget-pkgs/issues/new).
 - **Matrix chat:** Join the [WinGet-pkgs Matrix room](https://gitter.im/Microsoft/winget-pkgs) for quick questions.