refactor: reduce main() complexity and fix lint issues

- Split main() into _handle_install/_handle_wheel/_handle_binary/
  _handle_auto_detect handlers (fixes C901 complexity)
- Replace blind except Exception with specific OSError/ValueError/
  SystemExit (fixes BLE001)
- Remove unnecessary else after return (fixes RET505)
- Remove unused MIN_VERSION/MAX_VERSION imports
- Update gen_cli_docs.py to handle subparsers
- Extract _validate_wheel_tool helper

Author: shenxianpeng

clang_tools/main.py

@@ -12,7 +12,7 @@
 from typing import Optional
 
 from .install import install_clang_tools, uninstall_clang_tools
-from . import RESET_COLOR, YELLOW, MIN_VERSION, MAX_VERSION
+from . import RESET_COLOR, YELLOW
 from .util import Version
 
 
@@ -51,6 +51,118 @@ def _wheel_install(tools: list[str], version: Optional[str]) -> int:
     return 0 if ok else 1
 
 
+def _validate_wheel_tool(target: str) -> bool:
+    """Print an error and return `False` if *target* is not a wheel tool.
+    """
+    if target not in WHEEL_TOOLS:
+        print(
+            f"{YELLOW}Error: '{target}' is not available as a"
+            f" wheel. Supported: "
+            f"{', '.join(sorted(WHEEL_TOOLS))}{RESET_COLOR}",
+            file=sys.stderr,
+        )
+        return False
+    return True
+
+
+def _handle_wheel(args: argparse.Namespace) -> int:
+    """Handle ``install --wheel`` subcommand."""
+    target: str = args.target
+    if _is_version_like(target):
+        return _wheel_install(args.tool, target)
+    if not _validate_wheel_tool(target):
+        return 1
+    return _wheel_install([target], args.explicit_version)
+
+
+def _handle_binary(args: argparse.Namespace) -> int:
+    """Handle ``install --binary`` subcommand."""
+    target: str = args.target
+    if not _is_version_like(target):
+        print(
+            f"{YELLOW}Error: --binary requires a version number"
+            f" (got '{target}'){RESET_COLOR}",
+            file=sys.stderr,
+        )
+        return 1
+    version = Version(target)
+    if version.info == (0, 0, 0):
+        print(
+            f"{YELLOW}The version specified is not a semantic"
+            f" specification{RESET_COLOR}",
+            file=sys.stderr,
+        )
+        return 1
+    install_clang_tools(
+        version,
+        args.tool,
+        args.directory,
+        args.overwrite,
+        args.no_progress_bar,
+    )
+    return 0
+
+
+def _handle_auto_detect(args: argparse.Namespace) -> int:
+    """Handle ``install`` without --binary/--wheel (auto-detect mode)."""
+    target: str = args.target
+    if not _is_version_like(target):
+        if target not in WHEEL_TOOLS:
+            print(
+                f"{YELLOW}Unknown target '{target}'. Expected a"
+                f" version number or one of: "
+                f"{', '.join(sorted(WHEEL_TOOLS))}{RESET_COLOR}",
+                file=sys.stderr,
+            )
+            return 1
+        return _wheel_install([target], args.explicit_version)
+
+    version = Version(target)
+    if version.info == (0, 0, 0):
+        print(
+            f"{YELLOW}The version specified is not a semantic"
+            f" specification{RESET_COLOR}",
+            file=sys.stderr,
+        )
+        return 1
+
+    # try binary first, fall back to wheel
+    try:
+        install_clang_tools(
+            version,
+            args.tool,
+            args.directory,
+            args.overwrite,
+            args.no_progress_bar,
+        )
+        return 0
+    except (OSError, ValueError, SystemExit) as exc:
+        print(
+            f"{YELLOW}Binary install failed"
+            f" ({exc}), falling back to"
+            f" wheel...{RESET_COLOR}",
+            file=sys.stderr,
+        )
+    return _wheel_install(args.tool, target)
+
+
+def _handle_install(args: argparse.Namespace) -> int:
+    """Dispatch ``install`` subcommand based on flags."""
+    if args.binary and args.wheel:
+        print(
+            f"{YELLOW}Error: --binary and --wheel are mutually"
+            f" exclusive{RESET_COLOR}",
+            file=sys.stderr,
+        )
+        return 1
+
+    if args.wheel:
+        return _handle_wheel(args)
+    if args.binary:
+        return _handle_binary(args)
+    return _handle_auto_detect(args)
+
+
 def get_parser() -> argparse.ArgumentParser:
     """Get a parser to interpret CLI args (unified entry point)."""
     parser = argparse.ArgumentParser(
@@ -139,7 +251,6 @@ def main() -> int:
     parser = get_parser()
     args = parser.parse_args()
 
-    # ---- No subcommand → nothing to do ----------------------------------
     if args.command is None:
         print(
             f"{YELLOW}Nothing to do. Use 'install' or 'uninstall'"
@@ -149,110 +260,12 @@ def main() -> int:
         parser.print_help()
         return 0
 
-    # ---- ``uninstall`` subcommand ------------------------------------
     if args.command == "uninstall":
         uninstall_clang_tools(args.version, args.tool, args.directory)
         return 0
 
-    # ---- ``install`` subcommand --------------------------------------
     if args.command == "install":
-        target: str = args.target
-        binary: bool = args.binary
-        wheel: bool = args.wheel
-
-        # safety: --binary and --wheel are mutually exclusive
-        if binary and wheel:
-            print(
-                f"{YELLOW}Error: --binary and --wheel are mutually"
-                f" exclusive{RESET_COLOR}",
-                file=sys.stderr,
-            )
-            return 1
-
-        # ---- Case: --wheel (target may be tool name or version) -----
-        if wheel:
-            if _is_version_like(target):
-                # ``clang-tools install 18 --wheel``
-                return _wheel_install(args.tool, target)
-            else:
-                # ``clang-tools install clang-format --wheel``
-                if target not in WHEEL_TOOLS:
-                    print(
-                        f"{YELLOW}Error: '{target}' is not available as a"
-                        f" wheel. Supported: "
-                        f"{', '.join(sorted(WHEEL_TOOLS))}{RESET_COLOR}",
-                        file=sys.stderr,
-                    )
-                    return 1
-                return _wheel_install([target], args.explicit_version)
-
-        # ---- Case: --binary (target must be a version) --------------
-        if binary:
-            if not _is_version_like(target):
-                print(
-                    f"{YELLOW}Error: --binary requires a version number"
-                    f" (got '{target}'){RESET_COLOR}",
-                    file=sys.stderr,
-                )
-                return 1
-            version = Version(target)
-            if version.info != (0, 0, 0):
-                install_clang_tools(
-                    version,
-                    args.tool,
-                    args.directory,
-                    args.overwrite,
-                    args.no_progress_bar,
-                )
-                return 0
-            print(
-                f"{YELLOW}The version specified is not a semantic"
-                f" specification{RESET_COLOR}",
-                file=sys.stderr,
-            )
-            return 1
-
-        # ---- Auto-detect (no --binary or --wheel flag) --------------
-        if _is_version_like(target):
-            version = Version(target)
-            if version.info != (0, 0, 0):
-                # try binary first, fall back to wheel
-                try:
-                    install_clang_tools(
-                        version,
-                        args.tool,
-                        args.directory,
-                        args.overwrite,
-                        args.no_progress_bar,
-                    )
-                    return 0
-                except Exception as exc:
-                    print(
-                        f"{YELLOW}Binary install failed"
-                        f" ({exc}), falling back to"
-                        f" wheel...{RESET_COLOR}",
-                        file=sys.stderr,
-                    )
-                # fallback to wheel
-                return _wheel_install(args.tool, target)
-            else:
-                print(
-                    f"{YELLOW}The version specified is not a semantic"
-                    f" specification{RESET_COLOR}",
-                    file=sys.stderr,
-                )
-                return 1
-        else:
-            # target is a tool name → install via wheel
-            if target not in WHEEL_TOOLS:
-                print(
-                    f"{YELLOW}Unknown target '{target}'. Expected a"
-                    f" version number or one of: "
-                    f"{', '.join(sorted(WHEEL_TOOLS))}{RESET_COLOR}",
-                    file=sys.stderr,
-                )
-                return 1
-            return _wheel_install([target], args.explicit_version)
+        return _handle_install(args)
 
     return 0  # unreachable
 

docs/gen_cli_docs.py

@@ -17,11 +17,43 @@
 }
 
 
+def _action_doc(arg) -> str:
+    """Generate markdown for a single argparse action."""
+    aliases = arg.option_strings
+    if not aliases or arg.default == "==SUPPRESS==":
+        return ""
+    if arg.help is None:
+        msg = f"Argument {aliases[0] if aliases else arg.dest} missing help text"
+        raise ValueError(msg)
+
+    lines = [f"### `{', '.join(aliases)}`\n"]
+
+    req_ver = next(
+        (ver for ver, names in REQUIRED_VERSIONS.items() if arg.dest in names),
+        "0.1.0",
+    )
+    badges = [f":material-tag-outline: **v{req_ver}**"]
+
+    if arg.default is not None:
+        default = (
+            " ".join(arg.default) if isinstance(arg.default, list) else arg.default
+        )
+        badges.append(f"Default: `{default}`")
+    if arg.default is False and arg.const is True:
+        badges.append("Accepts no value")
+
+    lines.append("   ".join(badges) + "\n")
+    lines.append(arg.help + "\n")
+    return "\n".join(lines)
+
+
 def _write_cli_doc(parser, prog_name: str) -> str:
     """Generate markdown documentation from an argparse parser."""
     lines = []
     lines.append(f"---\ntitle: {prog_name} CLI\n---\n")
     lines.append(f"# `{prog_name}` CLI Reference\n")
+
+    # Top-level usage
     lines.append("## Usage\n")
     lines.append("```text")
     parser.prog = prog_name
@@ -32,34 +64,36 @@ def _write_cli_doc(parser, prog_name: str) -> str:
     for line in usage.splitlines():
         lines.append(f"    {line[start:]}")
     lines.append("```\n")
-    lines.append("## Options\n")
 
-    args = parser._actions
-    for arg in args:
-        aliases = arg.option_strings
-        if not aliases or arg.default == "==SUPPRESS==":
+    # Top-level options (subcommands placeholder)
+    subparsers_action = None
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            subparsers_action = action
             continue
-        if arg.help is None:
-            msg = f"Argument {aliases[0] if aliases else arg.dest} missing help text"
-            raise ValueError(msg)
-        lines.append(f"### `{', '.join(aliases)}`\n")
-
-        req_ver = next(
-            (ver for ver, names in REQUIRED_VERSIONS.items() if arg.dest in names),
-            "0.1.0",
-        )
-        badges = [f":material-tag-outline: **v{req_ver}**"]
-
-        if arg.default is not None:
-            default = (
-                " ".join(arg.default) if isinstance(arg.default, list) else arg.default
-            )
-            badges.append(f"Default: `{default}`")
-        if arg.default is False and arg.const is True:
-            badges.append("Accepts no value")
-
-        lines.append("   ".join(badges) + "\n")
-        lines.append(arg.help + "\n")
+        doc = _action_doc(action)
+        if doc:
+            lines.append(doc)
+
+    # Subcommand details
+    if subparsers_action is not None:
+        for name, sub in subparsers_action.choices.items():
+            lines.append(f"---\n\n## `{prog_name} {name}`\n")
+            lines.append(f"```text")
+            sub.prog = f"{prog_name} {name}"
+            str_buf = StringIO()
+            sub.print_usage(str_buf)
+            sub_usage = str_buf.getvalue()
+            sub_start = sub_usage.find(sub.prog)
+            lines.append(f"    {sub_usage[sub_start:]}")
+            lines.append("```\n")
+
+            for action in sub._actions:
+                if not action.option_strings or action.default == "==SUPPRESS==":
+                    continue
+                doc = _action_doc(action)
+                if doc:
+                    lines.append(doc)
 
     return "\n".join(lines)