skills/generate-runbook/scripts/validate_runbook.py

#!/usr/bin/env python3
"""Lint the bundled Markdown format; never authorize or execute a procedure."""

from __future__ import annotations

import argparse
from datetime import date
import re
import sys
from pathlib import Path


REQUIRED_SECTIONS = (
    "Metadata", "Objective", "Scope", "Preconditions", "Risk and stop conditions",
    "Evidence plan", "Procedure", "Rollback", "Completion criteria",
    "Communications", "Record",
)
REQUIRED_FIELDS = {
    "Metadata": ("Status", "Owner", "Operator", "Go/no-go owner", "Last verified", "Environment",
                 "Expected duration", "Change/incident ID", "Runbook revision", "Target artifact"),
    "Scope": ("Included", "Excluded", "Must remain unchanged"),
    "Preconditions": ("Entry signal", "Entry verification"),
    "Risk and stop conditions": ("Risk", "Stop immediately if"),
    "Evidence plan": ("Record", "Store in", "Never record", "Binding"),
    "Rollback": ("Trigger", "Decision owner", "Actions", "Verification", "Limitations"),
    "Communications": ("Start", "Failure", "Completion"),
    "Record": ("Execution record",),
}
STEP_FIELDS = (
    "Step ID", "Action", "Expected result", "Verify", "If verification fails",
    "Approval required", "Retry safety",
)
SENSITIVE_PATTERNS = (
    re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----"),
    re.compile(r"\b(?:api[_-]?key|secret|password|token)\s*[:=]\s*[\"']?[A-Za-z0-9_./+=-]{12,}", re.I),
)


def normalize_heading(value: str) -> str:
    return re.sub(r"\s+", " ", value.strip()).casefold()


def prose(text: str) -> str:
    """Exclude comments and fenced code from structural checks."""
    text = re.sub(r"<!--.*?-->", "", text, flags=re.S)
    lines = []
    fence = None
    for line in text.splitlines():
        marker = re.match(r"^\s{0,3}(`{3,}|~{3,})", line)
        if fence:
            if re.fullmatch(r"\s{0,3}" + re.escape(fence[0]) + r"{" + str(len(fence)) + r",}\s*", line):
                fence = None
        elif marker:
            fence = marker.group(1)
        else:
            lines.append(line)
    return "\n".join(lines)


def field_values(body: str) -> dict[str, str]:
    """Read inline template values and the three Scope block labels."""
    pattern = re.compile(
        r"^[ \t]*(?:(?:[-*]|\d+\.)[ \t]+)?(?:\*\*)?"
        r"([A-Za-z][A-Za-z /-]*?)(?::(?:\*\*)?|\*\*:?)[ \t]*(.*)$", re.M
    )
    matches = list(pattern.finditer(body))
    values = {}
    for i, match in enumerate(matches):
        name = normalize_heading(match.group(1))
        if name not in {"included", "excluded", "must remain unchanged"}:
            # A generic checklist after a blank field is not that field's value.
            values[name] = match.group(2).strip()
            continue
        end = matches[i + 1].start() if i + 1 < len(matches) else len(body)
        # A phase heading must not supply the value of an empty preceding field.
        value = re.split(r"^#{1,6}\s", body[match.start(2):end], maxsplit=1, flags=re.M)[0]
        values[name] = value.strip()
    return values


def placeholders(text: str) -> list[str]:
    # Links, images, reference links/definitions, footnotes, checkboxes and
    # inline code are not template placeholders. This is not a Markdown parser.
    definitions = set(re.findall(r"^\s*\[([^\]\n]+)\]:", text, re.M))
    text = re.sub(r"`+[^`\n]*`+", "", text)
    text = re.sub(r"^\s*\[[^\]\n]+\]:.*$", "", text, flags=re.M)
    text = re.sub(r"!?\[[^\]\n]*\](?:\([^\n]*?\)|\[[^\]\n]*\])", "", text)
    text = re.sub(r"\[\^[^\]\n]+\]|\[[ xX]\]", "", text)
    found = re.findall(r"\[[^\]\n]{2,80}\]|\b(?:TODO|TBD|UNSET|YYYY-MM-DD)\b", text)
    return [item for item in found if item.strip("[]") not in definitions]


def populated(value: str) -> bool:
    value = re.sub(r"^[\s*#\-\[\]]+", "", value).strip()
    return bool(value) and value.casefold() not in {"none", "n/a", "not applicable"}


def validate(path: Path, mode: str = "draft") -> tuple[list[str], list[str]]:
    if mode not in {"draft", "ready"}:
        raise ValueError("mode must be draft or ready")
    text = path.read_text(encoding="utf-8")
    body = prose(text)
    matches = list(re.finditer(r"^##\s+(.+?)\s*$", body, re.M))
    sections = {}
    errors: list[str] = []
    warnings: list[str] = []
    readiness = errors if mode == "ready" else warnings
    for i, match in enumerate(matches):
        name = normalize_heading(match.group(1))
        if name in sections:
            errors.append(f"duplicate section: {match.group(1)}")
        sections[name] = body[match.end():matches[i + 1].start() if i + 1 < len(matches) else len(body)].strip()

    for section in REQUIRED_SECTIONS:
        key = normalize_heading(section)
        if key not in sections:
            errors.append(f"missing required section: {section}")
        elif not populated(sections[key]):
            readiness.append(f"empty section or unexplained not-applicable value: {section}")

    for word, message in ((r"\bstop\b", "no explicit stop condition found"),
                          (r"\bverif(?:y|ication)\b", "no verification instruction found"),
                          (r"\brollback\b", "no rollback coverage found")):
        if not re.search(word, body, re.I):
            errors.append(message)

    fields = {name: field_values(sections.get(normalize_heading(name), ""))
              for name in REQUIRED_FIELDS}
    for section, labels in REQUIRED_FIELDS.items():
        for label in labels:
            if not populated(fields[section].get(normalize_heading(label), "")):
                readiness.append(f"missing populated field: {section} / {label}")

    status = fields["Metadata"].get("status", "").casefold()
    if mode == "ready" and status not in {"approved", "in progress"}:
        errors.append("ready mode requires Status: Approved or In progress; this is a declaration, not proof of approval")
    if mode == "draft" and status in {"approved", "in progress"}:
        warnings.append("execution status declared; run --mode ready before execution")
    verified = fields["Metadata"].get("last verified", "")
    try:
        if not re.fullmatch(r"\d{4}-\d{2}-\d{2}", verified):
            raise ValueError
        if date.fromisoformat(verified) > date.today():
            raise ValueError
    except ValueError:
        readiness.append("Last verified must be a real, non-future YYYY-MM-DD date")

    procedure = sections.get("procedure", "")
    actions = list(re.finditer(r"^\s*\d+\.\s+\*\*Action:\*\*", procedure, re.M))
    if not actions:
        readiness.append("Procedure requires numbered **Action:** steps in the bundled format")
    seen_ids = set()
    for i, action in enumerate(actions):
        step = field_values(procedure[action.start():actions[i + 1].start() if i + 1 < len(actions) else len(procedure)])
        for label in STEP_FIELDS:
            if not populated(step.get(normalize_heading(label), "")):
                readiness.append(f"step {i + 1}: missing populated {label}")
        step_id = step.get("step id", "").strip("`")
        if not re.fullmatch(r"[A-Za-z][A-Za-z0-9_-]*", step_id):
            readiness.append(f"step {i + 1}: Step ID must be a stable identifier")
        elif step_id in seen_ids:
            readiness.append(f"duplicate Step ID: {step_id}")
        seen_ids.add(step_id)

    unresolved = placeholders(body)
    if unresolved:
        readiness.append(f"{len(unresolved)} unresolved template placeholder(s)")
    for pattern in SENSITIVE_PATTERNS:
        if pattern.search(text):
            errors.append("possible secret or private key found")
            break
    return errors, warnings


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("runbook", type=Path)
    parser.add_argument("--mode", choices=("draft", "ready"), default="draft")
    args = parser.parse_args()
    try:
        errors, warnings = validate(args.runbook, args.mode)
    except (OSError, UnicodeError) as error:
        print(f"ERROR: cannot read runbook: {error}")
        return 2
    for issue in errors:
        print(f"ERROR: {issue}")
    for issue in warnings:
        print(f"WARNING: {issue}")
    if not errors:
        print(f"PASS: {args.mode} structural checks passed: {args.runbook}")
        print("Not authorization or proof of live state, evidence validity, command safety, or operational readiness.")
    return 1 if errors else 0


if __name__ == "__main__":
    sys.exit(main())