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