From b74b59889121e8dc3bbe10af6b65022a16dc20f4 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Mon, 14 Sep 2026 18:39:38 +0200 Subject: [PATCH] Another check & default change --- Jenkinsfile | 522 +++++++++++------------------- README.md | 4 +- WindowsMaintenanceReport.ps1 | 11 +- tools/check_powershell.py | 608 +++++++++++++++++++++++++++++++++++ 4 files changed, 801 insertions(+), 344 deletions(-) create mode 100644 tools/check_powershell.py diff --git a/Jenkinsfile b/Jenkinsfile index 4070fb4..d3fa96d 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -4,11 +4,13 @@ pipeline { agent { label 'rust_no_docker' } - environment { - POWERSHELL_TELEMETRY_OPTOUT = '1' + options { + // We handle checkout explicitly below. + skipDefaultCheckout(true) + } - // Keep PowerShell modules inside the Jenkins workspace. - PS_MODULE_HOME = "${WORKSPACE}/.tools/psmodules" + environment { + PYTHONUNBUFFERED = '1' } stages { @@ -41,6 +43,10 @@ pipeline { echo "Git:" git --version + echo + echo "Python:" + python3 --version + echo echo "Repository:" git status --short @@ -48,350 +54,35 @@ pipeline { } } - stage('Setup PowerShell') { + stage('Validate CI Tools') { steps { sh ''' set -eu - # --------------------------------------------------------- - # PowerShell - # --------------------------------------------------------- - # - # WinDiagnostics itself targets Windows, but PowerShell - # Core is used here only for static parsing and linting. - # - # On this FreeBSD worker, pwsh should normally be provided - # by the existing worker environment. - # --------------------------------------------------------- - - if command -v pwsh >/dev/null 2>&1; then - echo "PowerShell already installed." - else - echo "ERROR: pwsh was not found on this Jenkins worker." >&2 - echo >&2 - echo "Install PowerShell on the rust_no_docker worker:" >&2 - echo " pkg install powershell" >&2 + if ! command -v python3 >/dev/null 2>&1; then + echo "ERROR: python3 is required for WinDiagnostics CI." >&2 exit 1 fi - echo - echo "Using:" - pwsh --version - - pwsh \ - -NoLogo \ - -NoProfile \ - -NonInteractive \ - -Command ' - $ErrorActionPreference = "Stop" - - if ($PSVersionTable.PSVersion.Major -lt 7) { - throw "PowerShell 7 or later is required." - } - - $PSVersionTable | - Out-String | - Write-Host - ' - ''' - } - } - - stage('PowerShell Syntax') { - steps { - sh ''' - set -eu - - echo "Checking PowerShell syntax..." - echo - - pwsh \ - -NoLogo \ - -NoProfile \ - -NonInteractive \ - -Command ' - $ErrorActionPreference = "Stop" - - $paths = @( - git -c core.quotePath=false ls-files -- \ - "*.ps1" \ - "*.psm1" \ - "*.psd1" - ) - - if ($LASTEXITCODE -ne 0) { - throw "Unable to list tracked PowerShell files." - } - - $files = @( - $paths | - ForEach-Object { - Get-Item -LiteralPath $_ - } - ) - - if ($files.Count -eq 0) { - throw "No PowerShell files found." - } - - $failed = $false - - foreach ($file in $files) { - Write-Host "Parsing $($file.FullName)" - - $tokens = $null - $errors = $null - - [void][ - System.Management.Automation.Language.Parser - ]::ParseFile( - $file.FullName, - [ref]$tokens, - [ref]$errors - ) - - if ($errors.Count -gt 0) { - $failed = $true - - foreach ($parseError in $errors) { - Write-Host ( - "{0}:{1}:{2}: {3}" -f - $file.FullName, - $parseError.Extent.StartLineNumber, - $parseError.Extent.StartColumnNumber, - $parseError.Message - ) - } - } - } - - if ($failed) { - throw "PowerShell parser validation failed." - } - - Write-Host "" - Write-Host "All PowerShell files parsed successfully." - ' - ''' - } - } - - stage('Setup PSScriptAnalyzer') { - steps { - sh ''' - set -eu - - mkdir -p "${PS_MODULE_HOME}" - - pwsh \ - -NoLogo \ - -NoProfile \ - -NonInteractive \ - -Command ' - $ErrorActionPreference = "Stop" - $ProgressPreference = "SilentlyContinue" - - $moduleHome = $env:PS_MODULE_HOME - $separator = [IO.Path]::PathSeparator - - $env:PSModulePath = - $moduleHome + - $separator + - $env:PSModulePath - - if ( - -not ( - Get-Module \ - -ListAvailable \ - -Name PSScriptAnalyzer - ) - ) { - Write-Host ( - "Installing PSScriptAnalyzer into " + - "$moduleHome..." - ) - - Save-Module \ - PSScriptAnalyzer \ - -Path $moduleHome \ - -Repository PSGallery \ - -Force \ - -ErrorAction Stop - } - else { - Write-Host ( - "PSScriptAnalyzer already installed." - ) - } - - Import-Module \ - PSScriptAnalyzer \ - -ErrorAction Stop - - $module = Get-Module PSScriptAnalyzer - - Write-Host ( - "PSScriptAnalyzer version: " + - "$($module.Version)" - ) - ' - ''' - } - } - - stage('PSScriptAnalyzer') { - steps { - sh ''' - set -eu - - echo "Running PSScriptAnalyzer..." - echo - - pwsh \ - -NoLogo \ - -NoProfile \ - -NonInteractive \ - -Command ' - $ErrorActionPreference = "Stop" - - $separator = [IO.Path]::PathSeparator - - $env:PSModulePath = - $env:PS_MODULE_HOME + - $separator + - $env:PSModulePath - - Import-Module \ - PSScriptAnalyzer \ - -ErrorAction Stop - - $paths = @( - git -c core.quotePath=false ls-files -- \ - "*.ps1" \ - "*.psm1" \ - "*.psd1" - ) - - if ($LASTEXITCODE -ne 0) { - throw "Unable to list tracked PowerShell files." - } - - $files = @( - $paths | - ForEach-Object { - Get-Item -LiteralPath $_ - } - ) - - if ($files.Count -eq 0) { - throw "No PowerShell files found." - } - - $issues = @( - foreach ($file in $files) { - Invoke-ScriptAnalyzer \ - -Path $file.FullName \ - -Severity Error,Warning \ - -ErrorAction Stop - } - ) - - if ($issues.Count -gt 0) { - $issues | - Sort-Object \ - ScriptName, - Line, - Column | - Format-Table \ - Severity, - ScriptName, - Line, - Column, - RuleName, - Message \ - -AutoSize | - Out-String | - Write-Host - } - - $errors = @( - $issues | - Where-Object Severity -eq "Error" - ) - - $warnings = @( - $issues | - Where-Object Severity -eq "Warning" - ) - - Write-Host ( - "PSScriptAnalyzer: {0} error(s), " + - "{1} warning(s)." -f - $errors.Count, - $warnings.Count - ) - - # Warnings are informative. - # Analyzer errors fail CI. - if ($errors.Count -gt 0) { - throw ( - "PSScriptAnalyzer reported errors." - ) - } - ' - ''' - } - } - - stage('Validate JSON Contract') { - steps { - sh ''' - set -eu - - echo "Checking WinDiagnostics JSON report contract..." - echo - - if [ ! -f WindowsMaintenanceReport.ps1 ]; then - echo "ERROR: WindowsMaintenanceReport.ps1 is missing." >&2 + if [ ! -f tools/check_powershell.py ]; then + echo "ERROR: tools/check_powershell.py is missing." >&2 exit 1 fi - pwsh \ - -NoLogo \ - -NoProfile \ - -NonInteractive \ - -Command ' - $ErrorActionPreference = "Stop" + echo "Python validator found." + ''' + } + } - $script = Get-Content \ - -LiteralPath "./WindowsMaintenanceReport.ps1" \ - -Raw + stage('Validate PowerShell Sources') { + steps { + sh ''' + set -eu - $requiredMarkers = @( - "ConvertTo-Json", - "schema_version", - "report_type", - "generated_at", - "completed_at", - "sections" - ) + echo "Running lightweight PowerShell integrity checks..." + echo - foreach ($marker in $requiredMarkers) { - if (-not $script.Contains($marker)) { - throw ( - "Expected structured-report marker " + - "missing: $marker" - ) - } - - Write-Host "Found: $marker" - } - - Write-Host "" - Write-Host ( - "Structured JSON report contract looks valid." - ) - ' + python3 tools/check_powershell.py ''' } } @@ -402,10 +93,163 @@ pipeline { set -eu echo "Tracked PowerShell files:" - git ls-files -- '*.ps1' '*.psm1' '*.psd1' + echo + + ps_files="$(git ls-files -- '*.ps1' '*.psm1' '*.psd1')" + + if [ -z "${ps_files}" ]; then + echo "ERROR: no tracked PowerShell files found." >&2 + exit 1 + fi + + echo "${ps_files}" echo - echo "CI validation complete." + echo "Checking main report script..." + + if [ ! -f WindowsMaintenanceReport.ps1 ]; then + echo "ERROR: WindowsMaintenanceReport.ps1 is missing." >&2 + exit 1 + fi + + if [ ! -s WindowsMaintenanceReport.ps1 ]; then + echo "ERROR: WindowsMaintenanceReport.ps1 is empty." >&2 + exit 1 + fi + + echo + echo "Repository sanity checks passed." + ''' + } + } + + stage('Check JSON Report Contract') { + steps { + sh ''' + set -eu + + script="WindowsMaintenanceReport.ps1" + + echo "Checking structured report contract..." + echo + + required_markers=" + ConvertTo-Json + schema_version + report_type + generated_at + completed_at + sections + " + + failed=0 + + for marker in ${required_markers}; do + if grep -Fq "${marker}" "${script}"; then + echo "OK: ${marker}" + else + echo "ERROR: missing report marker: ${marker}" >&2 + failed=1 + fi + done + + if [ "${failed}" -ne 0 ]; then + echo >&2 + echo "Structured JSON report contract validation failed." >&2 + exit 1 + fi + + echo + echo "Structured JSON report contract looks valid." + ''' + } + } + + stage('Check Repository Hygiene') { + steps { + sh ''' + set -eu + + echo "Checking repository hygiene..." + echo + + failed=0 + + # --------------------------------------------------------- + # Merge conflict markers + # --------------------------------------------------------- + + if git grep -n \ + -e '^<<<<<<< ' \ + -e '^=======$' \ + -e '^>>>>>>> ' \ + -- \ + '*.ps1' \ + '*.psm1' \ + '*.psd1' + then + echo >&2 + echo "ERROR: unresolved merge conflict marker found." >&2 + failed=1 + else + echo "No merge conflict markers found." + fi + + # --------------------------------------------------------- + # Accidentally committed generated/debug files + # --------------------------------------------------------- + + suspicious="$( + git ls-files | + grep -E \ + '\\.(tmp|bak|old|orig|rej)$' \ + || true + )" + + if [ -n "${suspicious}" ]; then + echo >&2 + echo "WARNING: suspicious tracked backup/temp files:" + echo "${suspicious}" + else + echo "No obvious backup/temp files tracked." + fi + + if [ "${failed}" -ne 0 ]; then + exit 1 + fi + + echo + echo "Repository hygiene checks passed." + ''' + } + } + + stage('Summary') { + steps { + sh ''' + set -eu + + echo + echo "========================================" + echo " WinDiagnostics CI validation complete" + echo "========================================" + echo + echo "Checks performed:" + echo " - Git checkout" + echo " - Python availability" + echo " - PowerShell structural integrity" + echo " - Main script presence" + echo " - JSON report contract" + echo " - Merge conflict detection" + echo " - Repository hygiene" + echo + echo "NOTE:" + echo " PowerShell/CoreCLR cannot currently run" + echo " on this Jenkins FreeBSD worker." + echo + echo " CI therefore performs static structural" + echo " checks instead of invoking pwsh or" + echo " PSScriptAnalyzer." ''' } } @@ -417,7 +261,7 @@ pipeline { conclusion: 'SUCCESS', name: 'WinDiagnostics CI', summary: 'WinDiagnostics passed all CI integrity checks.', - text: 'PowerShell parsing, PSScriptAnalyzer, and JSON report contract validation completed successfully.', + text: 'Static PowerShell structural validation, repository checks, and JSON report contract validation completed successfully. PowerShell execution is intentionally disabled on this worker.', title: 'WinDiagnostics validation successful' ) @@ -429,7 +273,7 @@ pipeline { conclusion: 'FAILURE', name: 'WinDiagnostics CI', summary: 'WinDiagnostics failed CI.', - text: 'A checkout, PowerShell parsing, static analysis, or JSON contract validation step failed. Check the Jenkins log.', + text: 'A checkout, repository, PowerShell structural, or JSON report contract validation step failed. Check the Jenkins log.', title: 'WinDiagnostics CI failed' ) diff --git a/README.md b/README.md index 45c01aa..112e91f 100644 --- a/README.md +++ b/README.md @@ -153,7 +153,7 @@ This applies `ExecutionPolicy Bypass` only to that PowerShell process and does n ### Output Directory -Reports are saved in the current working directory when it is writable. +Reports are saved in the current user's Documents folder by default, including when Windows redirects that folder to OneDrive or a network location. Specify another directory with: @@ -167,7 +167,7 @@ This can be combined with a report level: .\WindowsMaintenanceReport.ps1 -Mid -OutputDirectory C:\Temp ``` -If no output directory is specified and the current directory is not writable, the script attempts to use the Windows temporary directory. +If no output directory is specified and the Documents folder is unavailable or not writable, the script attempts to use the Windows temporary directory. ### Event Log History diff --git a/WindowsMaintenanceReport.ps1 b/WindowsMaintenanceReport.ps1 index b4f7b38..be90a2d 100644 --- a/WindowsMaintenanceReport.ps1 +++ b/WindowsMaintenanceReport.ps1 @@ -336,9 +336,14 @@ function Invoke-NativeCommand { $isAdmin = Test-IsAdministrator if ([string]::IsNullOrWhiteSpace($OutputDirectory)) { - $candidate = (Get-Location).Path + # Resolve the Windows Documents folder, including redirected/OneDrive paths. + $candidate = [Environment]::GetFolderPath( + [Environment+SpecialFolder]::MyDocuments, + [Environment+SpecialFolderOption]::DoNotVerify + ) - if (Test-DirectoryWritable $candidate) { + if (-not [string]::IsNullOrWhiteSpace($candidate) -and + (Test-DirectoryWritable $candidate)) { $OutputDirectory = $candidate } elseif (Test-DirectoryWritable $env:TEMP) { @@ -900,4 +905,4 @@ Write-Host ('Report mode: ' + $mode) Write-Host ('Saved JSON report to: ' + $reportPath) # Return the path as the script result, useful for automation. -$reportPath \ No newline at end of file +$reportPath diff --git a/tools/check_powershell.py b/tools/check_powershell.py new file mode 100644 index 0000000..0e119ce --- /dev/null +++ b/tools/check_powershell.py @@ -0,0 +1,608 @@ +#!/usr/bin/env python3 + +""" +Lightweight PowerShell integrity checker for CI. + +This is NOT a full PowerShell parser. + +It is intended for environments where pwsh/CoreCLR cannot run, and checks: + +- UTF-8 readability +- NUL bytes +- Git conflict markers +- balanced (), [], {} +- quoted strings +- PowerShell here-strings +- block comments +- expected WinDiagnostics JSON report markers + +No external dependencies. +""" + +from __future__ import annotations + +import argparse +import pathlib +import sys + + +POWERSHELL_EXTENSIONS = {".ps1", ".psm1", ".psd1"} + +REQUIRED_REPORT_MARKERS = ( + "ConvertTo-Json", + "schema_version", + "report_type", + "generated_at", + "completed_at", + "sections", +) + +CONFLICT_MARKERS = ( + "<<<<<<<", + "=======", + ">>>>>>>", +) + + +class ValidationError: + def __init__( + self, + path: pathlib.Path, + line: int, + column: int, + message: str, + ) -> None: + self.path = path + self.line = line + self.column = column + self.message = message + + def __str__(self) -> str: + return ( + f"{self.path}:{self.line}:{self.column}: " + f"{self.message}" + ) + + +def position(text: str, offset: int) -> tuple[int, int]: + line = text.count("\n", 0, offset) + 1 + last_newline = text.rfind("\n", 0, offset) + + if last_newline < 0: + column = offset + 1 + else: + column = offset - last_newline + + return line, column + + +def validate_structure( + path: pathlib.Path, + text: str, +) -> list[ValidationError]: + errors: list[ValidationError] = [] + + stack: list[tuple[str, int]] = [] + + matching = { + ")": "(", + "]": "[", + "}": "{", + } + + opening = set(matching.values()) + closing = set(matching.keys()) + + i = 0 + length = len(text) + + quote: str | None = None + quote_start = 0 + + block_comment = False + block_comment_start = 0 + + here_string: str | None = None + here_string_start = 0 + + while i < length: + ch = text[i] + nxt = text[i + 1] if i + 1 < length else "" + + # ------------------------------------------------------------- + # Here strings + # + # @" ... "@ + # @' ... '@ + # ------------------------------------------------------------- + + if here_string is not None: + if ch == "\n": + line_start = i + 1 + + if here_string == '"': + terminator = '"@' + else: + terminator = "'@" + + if text.startswith(terminator, line_start): + here_string = None + i = line_start + 2 + continue + + i += 1 + continue + + # ------------------------------------------------------------- + # Block comments + # + # <# ... #> + # ------------------------------------------------------------- + + if block_comment: + if ch == "#" and nxt == ">": + block_comment = False + i += 2 + continue + + i += 1 + continue + + # ------------------------------------------------------------- + # Quoted strings + # ------------------------------------------------------------- + + if quote is not None: + if ch == "`": + # PowerShell escape character. + i += 2 + continue + + if ch == quote: + # PowerShell single quoted strings escape a quote by + # doubling it: + # + # 'It''s valid' + if ( + quote == "'" + and nxt == "'" + ): + i += 2 + continue + + quote = None + + i += 1 + continue + + # ------------------------------------------------------------- + # Line comments + # ------------------------------------------------------------- + + if ch == "#": + newline = text.find("\n", i) + + if newline < 0: + break + + i = newline + 1 + continue + + # ------------------------------------------------------------- + # Block comment start + # ------------------------------------------------------------- + + if ch == "<" and nxt == "#": + block_comment = True + block_comment_start = i + i += 2 + continue + + # ------------------------------------------------------------- + # Here-string start + # + # PowerShell requires the opening marker at the end of a line. + # This test deliberately keeps detection conservative. + # ------------------------------------------------------------- + + if ch == "@" and nxt in ('"', "'"): + after = i + 2 + + if ( + after >= length + or text[after] in "\r\n" + ): + here_string = nxt + here_string_start = i + i += 2 + continue + + # ------------------------------------------------------------- + # Normal strings + # ------------------------------------------------------------- + + if ch in ('"', "'"): + quote = ch + quote_start = i + i += 1 + continue + + # ------------------------------------------------------------- + # Escape outside strings + # ------------------------------------------------------------- + + if ch == "`": + i += 2 + continue + + # ------------------------------------------------------------- + # Delimiters + # ------------------------------------------------------------- + + if ch in opening: + stack.append((ch, i)) + + elif ch in closing: + expected = matching[ch] + + if not stack: + line, column = position(text, i) + + errors.append( + ValidationError( + path, + line, + column, + f"unexpected closing delimiter {ch!r}", + ) + ) + + else: + actual, actual_offset = stack.pop() + + if actual != expected: + line, column = position(text, i) + + errors.append( + ValidationError( + path, + line, + column, + ( + f"closing delimiter {ch!r} " + f"does not match {actual!r}" + ), + ) + ) + + open_line, open_column = position( + text, + actual_offset, + ) + + errors.append( + ValidationError( + path, + open_line, + open_column, + ( + f"unmatched opening delimiter " + f"{actual!r}" + ), + ) + ) + + i += 1 + + # ----------------------------------------------------------------- + # EOF checks + # ----------------------------------------------------------------- + + if quote is not None: + line, column = position(text, quote_start) + + errors.append( + ValidationError( + path, + line, + column, + f"unterminated {quote} string", + ) + ) + + if block_comment: + line, column = position( + text, + block_comment_start, + ) + + errors.append( + ValidationError( + path, + line, + column, + "unterminated PowerShell block comment", + ) + ) + + if here_string is not None: + line, column = position( + text, + here_string_start, + ) + + errors.append( + ValidationError( + path, + line, + column, + "unterminated PowerShell here-string", + ) + ) + + for delimiter, offset in stack: + line, column = position(text, offset) + + errors.append( + ValidationError( + path, + line, + column, + f"unclosed delimiter {delimiter!r}", + ) + ) + + return errors + + +def validate_common( + path: pathlib.Path, + raw: bytes, +) -> tuple[str | None, list[ValidationError]]: + errors: list[ValidationError] = [] + + if not raw: + errors.append( + ValidationError( + path, + 1, + 1, + "file is empty", + ) + ) + return "", errors + + if b"\x00" in raw: + errors.append( + ValidationError( + path, + 1, + 1, + "file contains NUL bytes", + ) + ) + + try: + text = raw.decode("utf-8-sig") + except UnicodeDecodeError as exc: + errors.append( + ValidationError( + path, + exc.start + 1, + 1, + f"file is not valid UTF-8: {exc}", + ) + ) + return None, errors + + for marker in CONFLICT_MARKERS: + offset = text.find(marker) + + if offset >= 0: + line, column = position(text, offset) + + errors.append( + ValidationError( + path, + line, + column, + ( + "possible unresolved Git conflict " + f"marker: {marker}" + ), + ) + ) + + return text, errors + + +def validate_report_contract( + path: pathlib.Path, + text: str, +) -> list[ValidationError]: + errors: list[ValidationError] = [] + + for marker in REQUIRED_REPORT_MARKERS: + if marker not in text: + errors.append( + ValidationError( + path, + 1, + 1, + ( + "structured-report contract marker " + f"is missing: {marker}" + ), + ) + ) + + return errors + + +def check_file( + path: pathlib.Path, + report_script: pathlib.Path, +) -> list[ValidationError]: + try: + raw = path.read_bytes() + except OSError as exc: + return [ + ValidationError( + path, + 1, + 1, + f"unable to read file: {exc}", + ) + ] + + text, errors = validate_common(path, raw) + + if text is None: + return errors + + errors.extend( + validate_structure( + path, + text, + ) + ) + + try: + is_report = ( + path.resolve() + == report_script.resolve() + ) + except OSError: + is_report = path == report_script + + if is_report: + errors.extend( + validate_report_contract( + path, + text, + ) + ) + + return errors + + +def discover(root: pathlib.Path) -> list[pathlib.Path]: + files = [] + + for path in root.rglob("*"): + if ".git" in path.parts: + continue + + if not path.is_file(): + continue + + if path.suffix.lower() in POWERSHELL_EXTENSIONS: + files.append(path) + + return sorted(files) + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser( + description=( + "Perform lightweight structural validation " + "of PowerShell source files." + ) + ) + + parser.add_argument( + "paths", + nargs="*", + type=pathlib.Path, + help=( + "PowerShell files to check. " + "If omitted, the current tree is scanned." + ), + ) + + parser.add_argument( + "--report-script", + type=pathlib.Path, + default=pathlib.Path( + "WindowsMaintenanceReport.ps1" + ), + help=( + "Script expected to implement the WinDiagnostics " + "structured JSON report contract." + ), + ) + + return parser.parse_args() + + +def main() -> int: + args = parse_args() + + if args.paths: + files = args.paths + else: + files = discover(pathlib.Path(".")) + + if not files: + print( + "ERROR: no PowerShell files found.", + file=sys.stderr, + ) + return 1 + + report_script = args.report_script + + if not report_script.exists(): + print( + f"ERROR: report script is missing: " + f"{report_script}", + file=sys.stderr, + ) + return 1 + + failed = False + + print( + f"Checking {len(files)} PowerShell file(s)..." + ) + print() + + for path in files: + errors = check_file( + path, + report_script, + ) + + if errors: + failed = True + print(f"FAIL: {path}") + + for error in errors: + print(f" {error}") + + else: + print(f"OK: {path}") + + print() + + if failed: + print( + "PowerShell mock validation failed.", + file=sys.stderr, + ) + return 1 + + print( + "PowerShell mock validation passed." + ) + + print( + "NOTE: this is a structural CI check, " + "not a real PowerShell parser." + ) + + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) \ No newline at end of file