WinDiagnostics/tools/check_powershell.py

608 lines
14 KiB
Python

#!/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())