608 lines
14 KiB
Python
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()) |