Honor ADOQR_OUTPUT_PATH env var as the default -OutputPath

The Dockerfile sets ENV ADOQR_OUTPUT_PATH=/reports and exposes /reports as a
VOLUME, but invoke-adoqr.ps1 never read that variable: -OutputPath defaulted to
$PSScriptRoot/assessments (i.e. /opt/adoqr/assessments in the image). Running
the container as documented without an explicit -OutputPath wrote reports to an
ephemeral in-container folder that was discarded on --rm, leaving the mounted
/reports volume empty.

Resolve the effective output directory with the precedence
-OutputPath argument > $env:ADOQR_OUTPUT_PATH > assessments/ next to the script,
via a small testable helper (Resolve-AdoqrOutputPath). An explicit -OutputPath
still takes precedence, so existing usage is unchanged.

- Add Resolve-AdoqrOutputPath and wire it into Main using PSBoundParameters to
  distinguish an explicit -OutputPath from the default.
- Update -OutputPath comment-based help and the Dockerfile usage notes.
- Add Pester coverage (tests/OutputPath.Tests.ps1) and register the helper in
  the test bootstrap.
- Record the fix in CHANGELOG under Unreleased.

Author: ngtanthanh-qc

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to Semantic Versioning.
 - Top navigation now includes an Extensions anchor placed before Run Comparison for faster access to extension findings.
 
 ### Fixed
+- `-OutputPath` now falls back to the `ADOQR_OUTPUT_PATH` environment variable when it is not supplied, so the Docker image's `ENV ADOQR_OUTPUT_PATH=/reports` (previously read by nothing) is honored. Reports generated from the container now land on the mounted `/reports` volume by default instead of an ephemeral in-container folder that was discarded on `--rm`. An explicit `-OutputPath` still takes precedence.
 - Auto-opening the executive HTML report at the end of a run now uses the platform-native opener (`open` on macOS, `xdg-open` on Linux, `Start-Process` on Windows) instead of `Start-Process` for all platforms, which raised `Permission denied` on macOS/Linux because PowerShell tried to execute the `.html` file as a binary.
 - Pipeline Authorization Scope checks now evaluate effective scope using project/org pipeline settings (`enforceJobAuthScope` and `enforceJobAuthScopeForReleases`) before pipeline-level values, preventing false positives when scope is enforced at project level.
 - Organization policy checks now evaluate policy `value` (with safe casing/boolean normalization) and include the new helper functions in parallel runspace serialization, fixing false results for `OAUTH-02` (SSH Access Disabled) and aligning `OAUTH-01` with the actual policy state.

Dockerfile

@@ -5,7 +5,11 @@
 #     -v $(pwd)/reports:/reports \
 #     -v $HOME/.azure:/root/.azure \
 #     ghcr.io/microsoft/adoqr:latest \
-#     -Organization MyOrg -OutputPath /reports -OutputFormat all
+#     -Organization MyOrg -OutputFormat all
+#
+# Reports are written to /reports by default via the ADOQR_OUTPUT_PATH env var
+# set below, which is exposed as a volume — bind-mount a host path to keep them
+# after the container exits. Pass -OutputPath to override the destination.
 #
 # To authenticate non-interactively, mount your existing Azure CLI profile
 # (~/.azure) into the container as shown above, or run `az login` inside the

invoke-adoqr.ps1

@@ -14,7 +14,10 @@
 .PARAMETER Project
     Optional. One or more project names. If omitted, all projects are assessed.
 .PARAMETER OutputPath
-    Directory for report files. Defaults to current directory.
+    Directory for report files. When omitted, falls back to the
+    ADOQR_OUTPUT_PATH environment variable if it is set (the Docker image uses
+    this to target its /reports volume), otherwise an "assessments" folder next
+    to this script. Each run writes to a timestamped subfolder under it.
 .PARAMETER MaxParallel
     Maximum concurrency for project assessment. Default 3.
     Requires PowerShell 7+ for parallel execution. Values 2-4 recommended to avoid ADO rate limiting.
@@ -5529,6 +5532,36 @@ function Import-AdoqrSettings {
     return $settings
 }
 
+function Resolve-AdoqrOutputPath {
+    <#
+    .SYNOPSIS
+        Resolves the effective report output directory.
+    .DESCRIPTION
+        Applies the output-directory precedence: an explicit -OutputPath
+        argument wins; otherwise the ADOQR_OUTPUT_PATH environment variable is
+        honored when set (this is how the Docker image points reports at its
+        /reports volume); otherwise the supplied default is used. Empty or
+        whitespace-only values are treated as "not provided".
+    .PARAMETER ExplicitPath
+        The value passed via -OutputPath, or $null/empty when the caller did
+        not specify it.
+    .PARAMETER EnvPath
+        The ADOQR_OUTPUT_PATH environment variable value (may be $null/empty).
+    .PARAMETER DefaultPath
+        Fallback directory when neither of the above is provided.
+    #>
+    [CmdletBinding()]
+    param(
+        [string]$ExplicitPath,
+        [string]$EnvPath,
+        [string]$DefaultPath
+    )
+
+    if (-not [string]::IsNullOrWhiteSpace($ExplicitPath)) { return $ExplicitPath }
+    if (-not [string]::IsNullOrWhiteSpace($EnvPath))      { return $EnvPath }
+    return $DefaultPath
+}
+
 #endregion
 
 #region Main
@@ -5555,6 +5588,13 @@ $script:ExtMgmtUrl = "https://extmgmt.dev.azure.com/$OrgShortName"
 $script:AuditUrl   = "https://auditservice.dev.azure.com/$OrgShortName"
 $script:FeedsUrl   = "https://feeds.dev.azure.com/$OrgShortName"
 
+# Resolve the effective output directory.
+# Precedence: -OutputPath argument > $env:ADOQR_OUTPUT_PATH > assessments/ next
+# to the script. Honoring ADOQR_OUTPUT_PATH lets the Docker image direct reports
+# to its mounted /reports volume without callers having to pass -OutputPath.
+$explicitOutputPath = if ($PSBoundParameters.ContainsKey('OutputPath')) { $OutputPath } else { $null }
+$OutputPath = Resolve-AdoqrOutputPath -ExplicitPath $explicitOutputPath -EnvPath $env:ADOQR_OUTPUT_PATH -DefaultPath (Join-Path $PSScriptRoot 'assessments')
+
 # Ensure output directory exists — create timestamped subfolder per run
 $timestamp = Get-Date -Format "yyyy-MM-dd-HHmmss"
 $orgSafeForPath = ($OrgShortName -replace '[^a-zA-Z0-9\-]', '-').ToLower().Trim('-')

tests/OutputPath.Tests.ps1

@@ -0,0 +1,32 @@
+#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }
+
+BeforeAll {
+    . $PSScriptRoot/_Bootstrap.ps1
+}
+
+Describe 'Resolve-AdoqrOutputPath' {
+    It 'prefers an explicit -OutputPath over the env var and default' {
+        Resolve-AdoqrOutputPath -ExplicitPath '/explicit' -EnvPath '/env' -DefaultPath '/def' |
+            Should -Be '/explicit'
+    }
+
+    It 'honors ADOQR_OUTPUT_PATH when no explicit path is given' {
+        Resolve-AdoqrOutputPath -ExplicitPath $null -EnvPath '/env' -DefaultPath '/def' |
+            Should -Be '/env'
+    }
+
+    It 'treats a whitespace-only explicit path as not provided' {
+        Resolve-AdoqrOutputPath -ExplicitPath '   ' -EnvPath '/env' -DefaultPath '/def' |
+            Should -Be '/env'
+    }
+
+    It 'ignores an empty ADOQR_OUTPUT_PATH and uses the default' {
+        Resolve-AdoqrOutputPath -ExplicitPath $null -EnvPath '' -DefaultPath '/def' |
+            Should -Be '/def'
+    }
+
+    It 'falls back to the default when neither explicit nor env is set' {
+        Resolve-AdoqrOutputPath -ExplicitPath $null -EnvPath $null -DefaultPath '/def' |
+            Should -Be '/def'
+    }
+}

tests/_Bootstrap.ps1

@@ -35,6 +35,7 @@ $wantedFns = @(
     'Get-AdoqrHeaderCss'
     'Get-AdoqrHeaderHtml'
     'Import-AdoqrSettings'
+    'Resolve-AdoqrOutputPath'
 )
 
 $funcs = $tree.FindAll({