Skip to content

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

Python

fix(skill-generator): parse nested decorator arguments (#444)

陈家名429f39915027
diff --git a/cli-anything-plugin/skill_generator.py b/cli-anything-plugin/skill_generator.py
index 1f754fadf..7c77a4bb6 100644
--- a/cli-anything-plugin/skill_generator.py
+++ b/cli-anything-plugin/skill_generator.py
@@ -11,6 +11,7 @@ The generated SKILL.md files contain:
- Examples for AI agents
"""
+import ast
import re
from pathlib import Path
from typing import Optional
@@ -30,14 +31,50 @@ def _canonical_skill_name(harness_path: Path, software_name: str) -> str:
return f"cli-anything-{software_dir.replace('_', '-')}"
-def _click_declared_name(decorator_args: str, fallback: str) -> str:
- """Return the Click command/group name declared in a decorator."""
- match = re.search(r'^\s*["\']([^"\']+)["\']', decorator_args)
- if not match:
- match = re.search(r'\bname\s*=\s*["\']([^"\']+)["\']', decorator_args)
- if match:
- return match.group(1)
- return fallback.replace("_", "-")
+def _click_decorator_info(
+ function: ast.FunctionDef | ast.AsyncFunctionDef,
+ kind: str,
+) -> Optional[tuple[str, str]]:
+ """Return the owner and declared name for a Click decorator."""
+ for decorator in function.decorator_list:
+ target = decorator.func if isinstance(decorator, ast.Call) else decorator
+ if not (
+ isinstance(target, ast.Attribute)
+ and target.attr == kind
+ and isinstance(target.value, ast.Name)
+ ):
+ continue
+
+ declared_name = None
+ if isinstance(decorator, ast.Call):
+ if decorator.args:
+ first_arg = decorator.args[0]
+ if (
+ isinstance(first_arg, ast.Constant)
+ and isinstance(first_arg.value, str)
+ ):
+ declared_name = first_arg.value
+ if declared_name is None:
+ for keyword in decorator.keywords:
+ if (
+ keyword.arg == "name"
+ and isinstance(keyword.value, ast.Constant)
+ and isinstance(keyword.value.value, str)
+ ):
+ declared_name = keyword.value.value
+ break
+
+ return target.value.id, declared_name or function.name.replace("_", "-")
+
+ return None
+
+
+def _function_docstring(function: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
+ """Return a function docstring without changing its internal formatting."""
+ docstring = ast.get_docstring(function, clean=False)
+ if docstring:
+ return docstring.strip()
+ return ""
@dataclass
@@ -211,41 +248,35 @@ def extract_version_from_setup(setup_path: Path) -> str:
def extract_commands_from_cli(cli_path: Path) -> list[CommandGroup]:
"""Extract command groups and commands from CLI file."""
content = cli_path.read_text(encoding="utf-8")
- groups = []
-
- # Find Click group decorators
- # Pattern handles:
- # - Multi-line decorators (decorators on separate lines)
- # - Docstrings on the same line or following line after function definition
- # - Various Click decorator patterns like @click.option(), @click.argument()
- # Uses re.DOTALL to match across newlines between decorator and def
- optional_decorator_pattern = r'(?:\s*@[\w.]+(?:\([^)]*\))?)*'
-
- group_pattern = (
- r'@(\w+)\.group\(([^)]*)\)' # @xxx.group(...)
- + optional_decorator_pattern # optional additional decorators
- + r'\s*def\s+(\w+)\([^)]*\)' # def xxx(...):
- + r':\s*' # colon with optional whitespace
- + r'(?:"""([\s\S]*?)"""|\'\'\'([\s\S]*?)\'\'\')?' # optional docstring (""" or ''')
+ tree = ast.parse(content, filename=str(cli_path))
+ functions = sorted(
+ (
+ node
+ for node in ast.walk(tree)
+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+ ),
+ key=lambda node: (node.lineno, node.col_offset),
)
+ groups = []
group_lookup = {}
group_display_paths = {}
- group_matches = list(re.finditer(group_pattern, content))
+ group_functions = [
+ (function, decorator_info)
+ for function in functions
+ if (decorator_info := _click_decorator_info(function, "group"))
+ ]
root_group_funcs = {
- match.group(3).lower()
- for match in group_matches
- if match.group(1).lower() == "click"
+ function.name.lower()
+ for function, (parent, _) in group_functions
+ if parent.lower() == "click"
}
- for match in group_matches:
- group_parent = match.group(1)
- group_args = match.group(2)
- group_func = match.group(3)
- # Docstring can be in group 4 (triple-double) or group 5 (triple-single)
- group_doc = (match.group(4) or match.group(5) or "").strip()
+ for function, (group_parent, declared_name) in group_functions:
+ group_func = function.name
+ group_doc = _function_docstring(function)
- local_group_name = _format_display_name(_click_declared_name(group_args, group_func))
+ local_group_name = _format_display_name(declared_name)
parent_key = group_parent.lower()
if parent_key == "click" or parent_key in root_group_funcs:
group_path = [local_group_name]
@@ -267,32 +298,21 @@ def extract_commands_from_cli(cli_path: Path) -> list[CommandGroup]:
group_lookup[group_func.lower()] = group
group_display_paths[group_func.lower()] = group_path
- # Find Click command decorators
- # Pattern handles:
- # - Multi-line decorators (decorators on separate lines)
- # - Docstrings on the same line or following line after function definition
- # - Various Click decorator patterns like @click.option(), @click.argument()
- command_pattern = (
- r'@(\w+)\.command\(([^)]*)\)' # @xxx.command(...)
- + optional_decorator_pattern # optional additional decorators
- + r'\s*def\s+(\w+)\([^)]*\)' # def xxx(...):
- + r':\s*' # colon with optional whitespace
- + r'(?:"""([\s\S]*?)"""|\'\'\'([\s\S]*?)\'\'\')?' # optional docstring (""" or ''')
- )
+ command_functions = [
+ (function, decorator_info)
+ for function in functions
+ if (decorator_info := _click_decorator_info(function, "command"))
+ ]
- for match in re.finditer(command_pattern, content):
- group_name = match.group(1)
- cmd_args = match.group(2)
- cmd_func = match.group(3)
- # Docstring can be in group 4 (triple-double) or group 5 (triple-single)
- cmd_doc = (match.group(4) or match.group(5) or "").strip()
+ for function, (group_name, declared_name) in command_functions:
+ cmd_func = function.name
+ cmd_doc = _function_docstring(function)
# Find the matching group
group = group_lookup.get(group_name.lower())
if group:
- cmd_name = _click_declared_name(cmd_args, cmd_func)
group.commands.append(CommandInfo(
- name=cmd_name,
+ name=declared_name,
description=cmd_doc or f"Execute {cmd_func} operation."
))
@@ -304,14 +324,11 @@ def extract_commands_from_cli(cli_path: Path) -> list[CommandGroup]:
commands=[]
)
- for match in re.finditer(command_pattern, content):
- cmd_args = match.group(2)
- cmd_func = match.group(3)
- # Docstring can be in group 4 (triple-double) or group 5 (triple-single)
- cmd_doc = (match.group(4) or match.group(5) or "").strip()
- cmd_name = _click_declared_name(cmd_args, cmd_func)
+ for function, (_, declared_name) in command_functions:
+ cmd_func = function.name
+ cmd_doc = _function_docstring(function)
default_group.commands.append(CommandInfo(
- name=cmd_name,
+ name=declared_name,
description=cmd_doc or f"Execute {cmd_func} operation."
))
diff --git a/cli-anything-plugin/tests/test_skill_generator.py b/cli-anything-plugin/tests/test_skill_generator.py
index c389273b4..2fca6804d 100644
--- a/cli-anything-plugin/tests/test_skill_generator.py
+++ b/cli-anything-plugin/tests/test_skill_generator.py
@@ -10,6 +10,7 @@ import os
import sys
import textwrap
import tempfile
+import time
from pathlib import Path
import pytest
@@ -26,6 +27,7 @@ else:
from skill_generator import (
extract_cli_metadata,
+ extract_commands_from_cli,
generate_skill_md,
generate_skill_md_simple,
generate_skill_file,
@@ -282,6 +284,82 @@ class TestExtractCliMetadata:
assert [cmd.name for cmd in groups["Devices"].commands] == ["list"]
assert [cmd.name for cmd in groups["Alerts Configs"].commands] == ["enable"]
+ def test_extracts_nested_decorator_arguments(self, tmp_path):
+ software = "nested_args"
+ cli_pkg = tmp_path / "cli_anything" / software
+ cli_pkg.mkdir(parents=True)
+ (cli_pkg / "__init__.py").write_text("")
+ (cli_pkg / f"{software}_cli.py").write_text(
+ textwrap.dedent("""\
+ import click
+ from pathlib import Path
+
+ @click.group(context_settings=dict(help_option_names=["-h", "--help"]))
+ @click.option("--format", type=click.Choice(["json", "text"]))
+ def cli(format):
+ pass
+
+ @cli.command(context_settings=dict(ignore_unknown_options=True))
+ @click.option("--output", type=click.Path(path_type=Path))
+ def render(output):
+ \"\"\"Render output.\"\"\"
+ pass
+ """)
+ )
+
+ metadata = extract_cli_metadata(str(tmp_path))
+ groups = {group.name: group for group in metadata.command_groups}
+
+ assert [cmd.name for cmd in groups["Cli"].commands] == ["render"]
+
+ def test_does_not_cross_annotated_decorated_function(self, tmp_path):
+ software = "annotated"
+ cli_pkg = tmp_path / "cli_anything" / software
+ cli_pkg.mkdir(parents=True)
+ (cli_pkg / "__init__.py").write_text("")
+ (cli_pkg / f"{software}_cli.py").write_text(
+ textwrap.dedent("""\
+ import click
+
+ @click.group(context_settings=dict(help_option_names=["-h", "--help"]))
+ @click.option("--json", is_flag=True)
+ def cli(json_output: bool) -> None:
+ pass
+
+ @cli.group("document")
+ def document_group():
+ \"\"\"Document commands.\"\"\"
+ pass
+
+ @document_group.command("new")
+ def new_document() -> None:
+ pass
+ """)
+ )
+
+ metadata = extract_cli_metadata(str(tmp_path))
+ groups = {group.name: group for group in metadata.command_groups}
+
+ assert list(groups) == ["Cli", "Document"]
+ assert [cmd.name for cmd in groups["Document"].commands] == ["new"]
+
+ def test_large_cli_extraction_avoids_regex_backtracking(self):
+ cli_path = (
+ _PLUGIN_DIR.parent
+ / "cc-switch"
+ / "agent-harness"
+ / "cli_anything"
+ / "ccswitch"
+ / "ccswitch_cli.py"
+ )
+
+ started_at = time.perf_counter()
+ groups = extract_commands_from_cli(cli_path)
+ elapsed = time.perf_counter() - started_at
+
+ assert groups
+ assert elapsed < 2.0
+
def test_generates_examples(self, harness_dir):
metadata = extract_cli_metadata(str(harness_dir))
assert len(metadata.examples) > 0