"""扫描仓库并生成参数位置报告。 输出文件:`state/param_locations.json`,包含: - functions: 列出所有函数定义及其参数 - argparse: 列出所有 argparse 的 add_argument 参数名 - track_param_calls: 列出所有 `track_param(...)` 调用位置与第一个参数(如果为字符串字面量) - track_call_calls: 列出所有 `track_call` 出现位置 用法: python tools/generate_param_locations.py """ from __future__ import annotations import ast import json import os import re from typing import Dict, List, Any ROOT = os.path.abspath(os.path.dirname(os.path.dirname(__file__))) OUT_PATH = os.path.join(ROOT, "state", "param_locations.json") def scan_py_file(path: str) -> Dict[str, List[Dict[str, Any]]]: res = { "functions": [], "argparse": [], "track_param_calls": [], "track_call_calls": [], } try: with open(path, "r", encoding="utf-8", errors="ignore") as f: src = f.read() except Exception: return res try: tree = ast.parse(src, filename=path) except Exception: # fallback to regex scanning for i, line in enumerate(src.splitlines(), 1): if "track_param(" in line: res["track_param_calls"].append( {"file": path, "line": i, "text": line.strip()} ) if "track_call(" in line or "@track_call" in line: res["track_call_calls"].append( {"file": path, "line": i, "text": line.strip()} ) if "add_argument(" in line: # try extract string args for m in re.finditer(r"([\'\"]--?[\w-]+[\'\"])", line): res["argparse"].append( {"file": path, "line": i, "arg": m.group(1).strip("'\"")} ) return res for node in ast.walk(tree): if isinstance(node, ast.FunctionDef): params = [] for a in node.args.args: params.append(a.arg) # include varargs/kw if node.args.vararg: params.append("*" + node.args.vararg.arg) if node.args.kwarg: params.append("**" + node.args.kwarg.arg) res["functions"].append( {"file": path, "line": node.lineno, "name": node.name, "params": params} ) if isinstance(node, ast.Call): # add_argument try: func = node.func func_name = None if isinstance(func, ast.Attribute): func_name = func.attr elif isinstance(func, ast.Name): func_name = func.id if func_name == "add_argument": # extract string literals from args for arg in node.args: if isinstance(arg, ast.Constant) and isinstance(arg.value, str): res["argparse"].append( {"file": path, "line": node.lineno, "arg": arg.value} ) # track_param calls if (isinstance(func, ast.Name) and func.id == "track_param") or ( isinstance(func, ast.Attribute) and func.attr == "track_param" ): first = None if node.args: a0 = node.args[0] if isinstance(a0, ast.Constant) and isinstance(a0.value, str): first = a0.value res["track_param_calls"].append( {"file": path, "line": node.lineno, "param_name": first} ) if (isinstance(func, ast.Name) and func.id == "track_call") or ( isinstance(func, ast.Attribute) and func.attr == "track_call" ): res["track_call_calls"].append({"file": path, "line": node.lineno}) except Exception: pass return res def main() -> int: out: Dict[str, List[Any]] = { "functions": [], "argparse": [], "track_param_calls": [], "track_call_calls": [], } for dirpath, dirs, files in os.walk(ROOT): # skip virtual envs and git if ".venv" in dirpath or ".git" in dirpath: continue for fn in files: if not fn.endswith(".py"): continue path = os.path.join(dirpath, fn) parts = scan_py_file(path) for k in out: out[k].extend(parts.get(k, [])) os.makedirs(os.path.dirname(OUT_PATH), exist_ok=True) with open(OUT_PATH, "w", encoding="utf-8") as f: json.dump( {"generated_at": __import__("time").time(), "report": out}, f, ensure_ascii=False, indent=2, ) print("written:", OUT_PATH) return 0 if __name__ == "__main__": raise SystemExit(main())