tools: add script to sync -O opt-level in rustc manpage with rustc --help

Author: jkelley129

src/doc/man/rustc.1

@@ -62,7 +62,7 @@ Comma separated list of compiler information to print on stdout.
 Equivalent to \fI\-C\ debuginfo=2\fR.
 .TP
 \fB\-O\fR
-Equivalent to \fI\-C\ opt\-level=2\fR.
+Equivalent to \fI\-C\ opt\-level=3\fR.
 .TP
 \fB\-o\fR \fIFILENAME\fR
 Write output to \fIFILENAME\fR. Ignored if multiple \fI\-\-emit\fR outputs are specified which

src/tools/update-rustc-man-opt-level.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT OR Apache-2.0
+r"""
+Update the rustc manpage "-O" description to match `rustc --help`.
+
+Usage (dry-run by default):
+  ./src/tools/update-rustc-man-opt-level.py --man-file src/doc/man/rustc.1
+
+Apply changes (creates a timestamped backup):
+  ./src/tools/update-rustc-man-opt-level.py --man-file src/doc/man/rustc.1 --apply
+
+Force a level instead of querying rustc:
+  ./src/tools/update-rustc-man-opt-level.py --man-file ... --expected-level 3 --apply
+"""
+from __future__ import annotations
+
+import argparse
+import datetime
+import difflib
+import shutil
+import subprocess
+import sys
+import re
+from pathlib import Path
+from typing import Tuple
+
+DEFAULT_RUSTC = "rustc"
+
+# ANSI color codes
+_CLR = {
+    "reset": "\033[0m",
+    "red": "\033[31m",
+    "green": "\033[32m",
+    "yellow": "\033[33m",
+    "bold": "\033[1m",
+}
+
+
+def colorize(line: str, color: str, enabled: bool) -> str:
+    if not enabled or color not in _CLR:
+        return line
+    return f"{_CLR[color]}{line}{_CLR['reset']}"
+
+
+def get_rustc_opt_level(rustc_cmd: str = DEFAULT_RUSTC) -> int:
+    """Query `rustc --help` and parse the opt-level mapped to -O."""
+    try:
+        proc = subprocess.run([rustc_cmd, "--help"], capture_output=True, text=True, check=True)
+    except FileNotFoundError:
+        raise RuntimeError(f"rustc not found at '{rustc_cmd}'")
+    except subprocess.CalledProcessError as e:
+        stderr = (e.stderr or "").strip()
+        raise RuntimeError(f"rustc --help failed: {stderr or e}") from e
+
+    help_text = (proc.stdout or "") + "\n" + (proc.stderr or "")
+    m = re.search(r'-O[^\n]*opt(?:\\-)?level\s*=\s*(\d+)', help_text, flags=re.IGNORECASE)
+    if not m:
+        m2 = re.search(r'Equivalent to\s+-C\s+opt(?:-)?level\s*=\s*(\d+)', help_text, flags=re.IGNORECASE)
+        if not m2:
+            raise RuntimeError("Could not find '-O' opt-level mapping in rustc --help output")
+        return int(m2.group(1))
+    return int(m.group(1))
+
+
+def find_and_replace_manpage_content(content: str, new_level: int) -> Tuple[str, int]:
+    """
+    Replace opt-level numbers in 'Equivalent to ... opt-level=N.' sentences tied to -O.
+
+    Conservative heuristic:
+      - Locate sentences starting with 'Equivalent to' up to the next period.
+      - Ensure the sentence mentions opt-level (accepting escaped '\-').
+      - Confirm a -O header appears within a lookback window before the sentence.
+    """
+    replacements = 0
+    out_parts = []
+    last_index = 0
+
+    sentence_pattern = re.compile(r'Equivalent to([^\n\.]{0,800}?)\.', flags=re.IGNORECASE)
+
+    for m in sentence_pattern.finditer(content):
+        start, end = m.span()
+        sentence = m.group(0)
+
+        if not re.search(r'opt(?:\\-)?level', sentence, flags=re.IGNORECASE):
+            continue
+
+        num_match = re.search(r'(\d+)', sentence)
+        if not num_match:
+            continue
+        old_level = int(num_match.group(1))
+        if old_level == new_level:
+            continue
+
+        window_start = max(0, start - 1200)
+        window = content[window_start:start]
+
+        if not (
+            re.search(r'(^|\n)\s*-O\b', window)
+            or re.search(r'\\fB\\-?O\\fR', window)
+            or re.search(r'\\-O\b', window)
+            or re.search(r'\.B\s+-O\b', window)
+            or re.search(r'\\fB-?O\\fP', window)
+        ):
+            continue
+
+        new_sentence = re.sub(r'(\d+)', str(new_level), sentence, count=1)
+        out_parts.append(content[last_index:start])
+        out_parts.append(new_sentence)
+        last_index = end
+        replacements += 1
+
+    out_parts.append(content[last_index:])
+    return "".join(out_parts), replacements
+
+
+def show_colored_diff(old: str, new: str, filename: str, color: bool) -> None:
+    old_lines = old.splitlines(keepends=True)
+    new_lines = new.splitlines(keepends=True)
+    diff_iter = difflib.unified_diff(old_lines, new_lines, fromfile=filename, tofile=filename + " (updated)", lineterm="")
+    for line in diff_iter:
+        if line.startswith("---") or line.startswith("+++"):
+            print(colorize(line.rstrip("\n"), "bold", color))
+        elif line.startswith("@@"):
+            print(colorize(line.rstrip("\n"), "yellow", color))
+        elif line.startswith("+"):
+            # avoid coloring the file header lines that also start with +++
+            print(colorize(line.rstrip("\n"), "green", color))
+        elif line.startswith("-"):
+            print(colorize(line.rstrip("\n"), "red", color))
+        else:
+            print(line.rstrip("\n"))
+
+
+def backup_file(path: Path) -> Path:
+    ts = datetime.datetime.now().strftime("%Y%m%dT%H%M%S")
+    backup = path.with_name(path.name + f".bak.{ts}")
+    shutil.copy2(path, backup)
+    return backup
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Update rustc man page -O opt-level to match rustc --help")
+    p.add_argument("--man-file", "-m", required=True, help="Path to rustc man page file to update (e.g. src/doc/man/rustc.1)")
+    p.add_argument("--rustc-cmd", default=DEFAULT_RUSTC, help="rustc binary to query (default: rustc)")
+    p.add_argument("--expected-level", "-e", type=int, help="Use this level instead of querying rustc")
+    p.add_argument("--apply", action="store_true", help="Write changes to the man file (creates a backup). Without this flag runs in dry-run mode and prints a diff.")
+    p.add_argument("--no-color", action="store_true", help="Disable colored output")
+    return p.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    color = (not args.no_color) and sys.stdout.isatty()
+
+    man_path = Path(args.man_file)
+    if not man_path.exists():
+        print(f"Error: man file not found: {man_path}", file=sys.stderr)
+        return 2
+
+    try:
+        new_level = args.expected_level if args.expected_level is not None else get_rustc_opt_level(args.rustc_cmd)
+    except RuntimeError as e:
+        print(f"Error determining rustc opt-level: {e}", file=sys.stderr)
+        return 3
+
+    try:
+        content = man_path.read_text(encoding="utf-8")
+    except Exception as e:
+        print(f"Error reading man file {man_path}: {e}", file=sys.stderr)
+        return 4
+
+    new_content, replacements = find_and_replace_manpage_content(content, new_level)
+
+    if replacements == 0:
+        print("No replacements necessary (either already up-to-date or -O entry not found near an 'Equivalent to -C opt-level=' line).")
+        return 0
+
+    header = f"Found {replacements} replacement(s). Proposed changes:"
+    print(colorize(header, "bold", color))
+    show_colored_diff(content, new_content, str(man_path), color)
+
+    if args.apply:
+        try:
+            backup = backup_file(man_path)
+            man_path.write_text(new_content, encoding="utf-8")
+            print(colorize(f"\nApplied changes to {man_path}. Backup saved to {backup}", "green", color))
+        except Exception as e:
+            print(f"Error writing updated man file: {e}", file=sys.stderr)
+            return 5
+    else:
+        print("\nDry-run only. Use --apply to write changes to disk.")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())