Another check & default change
WinDiagnostics CI WinDiagnostics passed all CI integrity checks.
Beffroi/WinDiagnostics/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-09-14 18:39:38 +02:00
parent e82316c57b
commit b74b598891
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
4 changed files with 801 additions and 344 deletions

522
Jenkinsfile vendored
View File

@ -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'
)

View File

@ -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

View File

@ -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
$reportPath

608
tools/check_powershell.py Normal file
View File

@ -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())