ast_grep_helper.py 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764
  1. #!/usr/bin/env python3
  2. """ast-grep-helper: a thin LLM-friendly wrapper around `sg` (ast-grep).
  3. Single-file Python 3 stdlib. No deps. Works on macOS, Linux, Windows, WSL.
  4. WHAT IT ADDS over plain `sg`:
  5. 1. Binary auto-resolution: cached -> @ast-grep/cli -> PATH -> Homebrew -> error with install hint
  6. 2. Pattern hint validation: detects regex misuse (\\w, .*, |, [a-z]) and language-specific
  7. mistakes (Python trailing colon, JS/Go/Rust missing function body) BEFORE calling sg
  8. 3. Two-pass replace: ast-grep silently ignores --update-all when --json is set, so we run
  9. a JSON pass to collect matches, then a separate --update-all pass to mutate files
  10. 4. Stable JSON output: parses sg --json=compact, salvages truncated output, normalizes shape
  11. 5. Cross-OS path handling: works the same on POSIX and Windows (uses pathlib + shutil)
  12. USAGE
  13. ast_grep_helper.py search PATTERN [PATH...] [--lang LANG] [--globs GLOB ...] [-C N]
  14. ast_grep_helper.py replace PATTERN REWRITE [PATH...] [--lang LANG] [--apply] [--globs GLOB ...]
  15. ast_grep_helper.py scan RULE_FILE [PATH...] [--apply] [--report-style STYLE]
  16. ast_grep_helper.py test [-c CONFIG] [-t TEST_DIR] [-U]
  17. ast_grep_helper.py new {project,rule,test,util} [NAME] [--lang LANG]
  18. ast_grep_helper.py langs # list 25 supported languages
  19. ast_grep_helper.py doctor # check binary availability + version
  20. ast_grep_helper.py install # delegate to ../install.sh / install.ps1
  21. ast_grep_helper.py validate PATTERN [--lang LANG] # offline pattern hint check only
  22. ast_grep_helper.py --version
  23. ast_grep_helper.py --help
  24. EXAMPLES
  25. # Find all console.log calls in TypeScript
  26. ast_grep_helper.py search 'console.log($MSG)' --lang ts src/
  27. # Migrate console.log -> logger.info (dry-run preview)
  28. ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/
  29. # Apply the same replacement
  30. ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/ --apply
  31. # Validate a pattern offline (no sg call, no filesystem access)
  32. ast_grep_helper.py validate '\\w+' --lang ts
  33. # -> exit 2, hint: "regex \\w not supported. Use $VAR for identifiers."
  34. EXIT CODES
  35. 0 Success (matches found OR replacement applied OR validation passed)
  36. 1 Argument error
  37. 2 Pattern hint failure (regex misuse, missing body, etc.) - call would have failed
  38. 3 ast-grep binary not found and auto-install declined
  39. 4 ast-grep call failed (returned non-zero, with stderr forwarded)
  40. 5 Timeout (5 minutes per call by default)
  41. """
  42. from __future__ import annotations
  43. import argparse
  44. import json
  45. import os
  46. import platform
  47. import re
  48. import shutil
  49. import subprocess
  50. import sys
  51. from pathlib import Path
  52. from typing import Optional
  53. VERSION = "0.1.0"
  54. # 25 CLI languages supported by ast-grep, with their aliases (mirrors official docs)
  55. LANGUAGES: dict[str, list[str]] = {
  56. "bash": [".bash", ".sh", ".zsh"],
  57. "c": [".c", ".h"],
  58. "cpp": [".cc", ".cpp", ".cxx", ".hpp", ".hxx"],
  59. "csharp": [".cs"],
  60. "css": [".css"],
  61. "elixir": [".ex", ".exs"],
  62. "go": [".go"],
  63. "haskell": [".hs"],
  64. "html": [".html", ".htm"],
  65. "java": [".java"],
  66. "javascript": [".js", ".jsx", ".cjs", ".mjs"],
  67. "json": [".json"],
  68. "kotlin": [".kt", ".kts"],
  69. "lua": [".lua"],
  70. "nix": [".nix"],
  71. "php": [".php"],
  72. "python": [".py", ".pyi"],
  73. "ruby": [".rb"],
  74. "rust": [".rs"],
  75. "scala": [".scala"],
  76. "solidity": [".sol"],
  77. "swift": [".swift"],
  78. "typescript": [".ts", ".cts", ".mts"],
  79. "tsx": [".tsx"],
  80. "yaml": [".yml", ".yaml"],
  81. }
  82. # Aliases that ast-grep CLI accepts; we normalize to the canonical name.
  83. LANG_ALIASES: dict[str, str] = {
  84. "js": "javascript", "jsx": "javascript",
  85. "ts": "typescript",
  86. "py": "python", "py3": "python",
  87. "rb": "ruby",
  88. "rs": "rust",
  89. "kt": "kotlin",
  90. "ex": "elixir",
  91. "hs": "haskell",
  92. "sh": "bash", "zsh": "bash",
  93. "cc": "cpp", "c++": "cpp", "cxx": "cpp",
  94. "cs": "csharp",
  95. "yml": "yaml",
  96. "sol": "solidity",
  97. "golang": "go",
  98. }
  99. # Default search timeout (5 min). ast-grep calls can be slow on huge repos.
  100. DEFAULT_TIMEOUT_S = 300
  101. # ---------- logging ----------
  102. def trace(msg: str) -> None:
  103. """Print a trace line to stderr (suppressible via --quiet, default off)."""
  104. if not _QUIET:
  105. print(f"[ast-grep-helper] {msg}", file=sys.stderr, flush=True)
  106. def err(msg: str) -> None:
  107. """Print an error line to stderr (always shown)."""
  108. print(f"[ast-grep-helper] error: {msg}", file=sys.stderr, flush=True)
  109. _QUIET = False
  110. # ---------- binary resolution ----------
  111. def script_dir() -> Path:
  112. return Path(__file__).resolve().parent
  113. def skill_root() -> Path:
  114. return script_dir().parent
  115. def cached_binary() -> Optional[Path]:
  116. """Look in <skill_root>/bin/ for a previously downloaded binary."""
  117. binname = "sg.exe" if os.name == "nt" else "sg"
  118. altname = "ast-grep.exe" if os.name == "nt" else "ast-grep"
  119. for name in (binname, altname):
  120. p = skill_root() / "bin" / name
  121. if p.is_file() and os.access(p, os.X_OK):
  122. return p
  123. return None
  124. def npm_binary() -> Optional[Path]:
  125. """If @ast-grep/cli is installed globally via npm, find its binary."""
  126. # `sg` shipped by @ast-grep/cli is on PATH when npm prefix bin is on PATH.
  127. # We rely on shutil.which for that case.
  128. return None # handled by which_binary
  129. def which_binary() -> Optional[Path]:
  130. """Use shutil.which to find sg or ast-grep on PATH.
  131. On Linux, plain `sg` collides with the setgroups command from util-linux
  132. (sometimes called via /usr/bin/sg) which has flag --version that returns
  133. non-zero, so we prefer `ast-grep` when both are on PATH and the `sg` we find
  134. is the wrong one.
  135. """
  136. for name in ("ast-grep", "sg"):
  137. found = shutil.which(name)
  138. if found:
  139. p = Path(found)
  140. # On Linux, double-check by trying --version. The util-linux `sg`
  141. # rejects --version, while ast-grep prints "ast-grep <version>".
  142. if name == "sg" and platform.system() == "Linux":
  143. try:
  144. out = subprocess.run(
  145. [str(p), "--version"],
  146. stdin=subprocess.DEVNULL, capture_output=True,
  147. text=True,
  148. timeout=5,
  149. check=False,
  150. )
  151. if out.returncode != 0 or "ast-grep" not in (out.stdout + out.stderr).lower():
  152. continue
  153. except Exception:
  154. continue
  155. return p
  156. return None
  157. def homebrew_binary() -> Optional[Path]:
  158. """Common Homebrew install paths."""
  159. candidates = [
  160. Path("/opt/homebrew/bin/ast-grep"),
  161. Path("/opt/homebrew/bin/sg"),
  162. Path("/usr/local/bin/ast-grep"),
  163. Path("/usr/local/bin/sg"),
  164. ]
  165. for p in candidates:
  166. if p.is_file() and os.access(p, os.X_OK):
  167. return p
  168. return None
  169. # --- OMO runtime resolution (vendored patch) ---
  170. def omo_env_binary() -> Optional[Path]:
  171. raw_path = os.environ.get("OMO_AST_GREP_SG_PATH")
  172. if not raw_path:
  173. return None
  174. path = Path(raw_path).expanduser()
  175. if path.is_file() and os.access(path, os.X_OK):
  176. return path
  177. return None
  178. def omo_runtime_slug() -> str:
  179. if sys.platform.startswith("win"):
  180. os_slug = "win32"
  181. elif sys.platform == "darwin":
  182. os_slug = "darwin"
  183. else:
  184. os_slug = "linux"
  185. machine = platform.machine().lower()
  186. arch_slug = "arm64" if machine in {"arm64", "aarch64"} else "x64"
  187. return f"{os_slug}-{arch_slug}"
  188. def omo_runtime_binary() -> Optional[Path]:
  189. binary_name = "sg.exe" if sys.platform.startswith("win") else "sg"
  190. slug = omo_runtime_slug()
  191. candidates: list[Path] = []
  192. codex_home = os.environ.get("CODEX_HOME")
  193. if codex_home:
  194. candidates.append(Path(codex_home) / "runtime" / "ast-grep" / slug / binary_name)
  195. candidates.append(Path.home() / ".omo" / "runtime" / "ast-grep" / slug / binary_name)
  196. for path in candidates:
  197. if path.is_file() and os.access(path, os.X_OK):
  198. return path
  199. return None
  200. def resolve_binary() -> Optional[Path]:
  201. """Resolve the ast-grep binary in priority order.
  202. 1. OMO_AST_GREP_SG_PATH override
  203. 2. OMO runtime dirs
  204. 3. Cached binary in <skill>/bin/
  205. 4. PATH (via shutil.which)
  206. 5. Homebrew default paths
  207. """
  208. for fn in (omo_env_binary, omo_runtime_binary, cached_binary, which_binary, homebrew_binary):
  209. result = fn()
  210. if result:
  211. return result
  212. return None
  213. def require_binary() -> Path:
  214. """Resolve binary, or print an actionable install hint and exit 3."""
  215. p = resolve_binary()
  216. if p:
  217. return p
  218. err("ast-grep binary not found.")
  219. err("")
  220. err("Install via one of:")
  221. err(f" bash {skill_root()}/install.sh # POSIX (auto-detects best method)")
  222. err(f" pwsh {skill_root()}/install.ps1 # Windows")
  223. err("")
  224. err("Or manually:")
  225. err(" brew install ast-grep # macOS / linuxbrew")
  226. err(" npm install -g @ast-grep/cli # any OS with Node")
  227. err(" cargo install ast-grep --locked # any OS with Rust")
  228. err(" pip install ast-grep-cli # any OS with Python")
  229. err(" scoop install main/ast-grep # Windows / Scoop")
  230. err("")
  231. err("See references/install.md for the full table.")
  232. sys.exit(3)
  233. # ---------- pattern hint validation ----------
  234. # Regex anti-patterns that ast-grep does NOT support but LLMs frequently emit.
  235. # Each tuple: (regex_to_detect, hint_message)
  236. REGEX_ANTIPATTERNS: list[tuple[re.Pattern[str], str]] = [
  237. (re.compile(r"\\w|\\d|\\s|\\b"),
  238. "Backslash escapes (\\w, \\d, \\s, \\b) are regex syntax, not ast-grep. "
  239. "Use $VAR to capture any identifier, or switch to grep for text patterns."),
  240. (re.compile(r"(?<!\$)\.\*|(?<!\$)\.\+"),
  241. "'.*' and '.+' are regex wildcards, not ast-grep. "
  242. "Use $$$ between AST fragments to match many nodes, or $VAR for one node."),
  243. (re.compile(r"\[[a-zA-Z0-9-]+\]"),
  244. "Character classes like '[a-z]' are regex syntax. "
  245. "ast-grep has no AST equivalent - use grep for character-level patterns."),
  246. ]
  247. def find_alternation(pattern: str) -> bool:
  248. """Detect a literal '|' that is not inside a string/template literal.
  249. Heuristic - mark as alternation if `|` appears outside obvious string contexts.
  250. """
  251. # Strip simple string contents to reduce false positives in patterns like
  252. # `'a|b'` or `"x|y"`. This is a heuristic, not a parser.
  253. stripped = re.sub(r"'[^']*'|\"[^\"]*\"|`[^`]*`", "", pattern)
  254. # Require word chars on both sides to avoid catching bitwise or ||
  255. return bool(re.search(r"\w\s*\|\s*\w", stripped)) and "||" not in stripped
  256. def lang_specific_hints(pattern: str, lang: Optional[str]) -> list[str]:
  257. """Return a list of hints for language-specific common mistakes."""
  258. if not lang:
  259. return []
  260. canonical = LANG_ALIASES.get(lang.lower(), lang.lower())
  261. hints: list[str] = []
  262. if canonical == "python":
  263. # def foo($$$): <-- trailing colon breaks the parse
  264. if re.search(r"^\s*(def|class)\s+\$?\w+[^:]*:\s*$", pattern, re.MULTILINE):
  265. hints.append(
  266. "Python pattern has trailing ':'. ast-grep parses pattern as a complete "
  267. "definition - drop the trailing colon. Try: 'def $FUNC($$$)' or 'class $C($$$)'."
  268. )
  269. if canonical in ("javascript", "typescript", "tsx"):
  270. if re.search(r"^\s*(async\s+)?function\s+\$?\w+\s*$", pattern):
  271. hints.append(
  272. "JS/TS function pattern is incomplete. Add params and body: "
  273. "'function $NAME($$$) { $$$ }'."
  274. )
  275. if canonical == "go":
  276. if re.search(r"^\s*func\s+\$?\w+\s*$", pattern):
  277. hints.append(
  278. "Go function pattern is incomplete. Add params and body: "
  279. "'func $NAME($$$) { $$$ }'."
  280. )
  281. if canonical == "rust":
  282. if re.search(r"^\s*fn\s+\$?\w+\s*$", pattern):
  283. hints.append(
  284. "Rust fn pattern is incomplete. Add params, return type, and body: "
  285. "'fn $NAME($$$) -> $RET { $$$ }' (or '-> ()' if returning unit)."
  286. )
  287. return hints
  288. def validate_pattern(pattern: str, lang: Optional[str]) -> list[str]:
  289. """Return a list of hints. Empty list = pattern looks plausible."""
  290. hints: list[str] = []
  291. for rx, msg in REGEX_ANTIPATTERNS:
  292. if rx.search(pattern):
  293. hints.append(msg)
  294. if find_alternation(pattern):
  295. hints.append(
  296. "Literal '|' alternation is regex syntax, not ast-grep. "
  297. "Run two separate ast-grep calls (one per alternative), or switch to grep."
  298. )
  299. hints.extend(lang_specific_hints(pattern, lang))
  300. return hints
  301. def normalize_lang(lang: Optional[str]) -> Optional[str]:
  302. if not lang:
  303. return None
  304. canonical = LANG_ALIASES.get(lang.lower(), lang.lower())
  305. if canonical not in LANGUAGES:
  306. err(f"unknown language '{lang}'. Run 'ast_grep_helper.py langs' for the full list.")
  307. sys.exit(1)
  308. return canonical
  309. # ---------- subprocess helpers ----------
  310. def run_sg(
  311. binary: Path,
  312. args: list[str],
  313. *,
  314. timeout: int = DEFAULT_TIMEOUT_S,
  315. capture: bool = True,
  316. ) -> subprocess.CompletedProcess[str]:
  317. """Spawn `sg <args>` with a hard timeout. Capture stdout/stderr by default."""
  318. cmd = [str(binary), *args]
  319. trace(f"exec: {' '.join(cmd)}")
  320. try:
  321. return subprocess.run(
  322. cmd,
  323. stdin=subprocess.DEVNULL, capture_output=capture,
  324. text=True,
  325. timeout=timeout,
  326. check=False,
  327. )
  328. except subprocess.TimeoutExpired:
  329. err(f"ast-grep call timed out after {timeout}s")
  330. sys.exit(5)
  331. # ---------- subcommands ----------
  332. def cmd_search(args: argparse.Namespace) -> int:
  333. pattern: str = args.pattern
  334. lang = normalize_lang(args.lang)
  335. hints = validate_pattern(pattern, lang)
  336. if hints:
  337. err("pattern looks invalid for ast-grep:")
  338. for h in hints:
  339. err(f" - {h}")
  340. if not args.force:
  341. err("(pass --force to call ast-grep anyway)")
  342. return 2
  343. binary = require_binary()
  344. sg_args = ["run", "-p", pattern, "--json=compact"]
  345. if lang:
  346. sg_args.extend(["--lang", lang])
  347. if args.context:
  348. sg_args.extend(["-C", str(args.context)])
  349. for g in args.globs or []:
  350. sg_args.extend(["--globs", g])
  351. sg_args.extend(args.paths or ["."])
  352. proc = run_sg(binary, sg_args)
  353. if proc.returncode not in (0, 1): # 0=match, 1=no match - both fine
  354. sys.stderr.write(proc.stderr or "")
  355. return 4
  356. matches = parse_compact_json(proc.stdout)
  357. if args.json_out:
  358. json.dump(matches, sys.stdout, indent=2)
  359. print()
  360. else:
  361. format_matches(matches)
  362. if not matches:
  363. # Re-run pattern hints in case empty result was caused by something subtle.
  364. # Already done above; here we just give a generic suggestion.
  365. trace("no matches. If you expected matches, double-check --lang and the pattern shape.")
  366. return 0
  367. def cmd_replace(args: argparse.Namespace) -> int:
  368. pattern: str = args.pattern
  369. rewrite: str = args.rewrite
  370. lang = normalize_lang(args.lang)
  371. pattern_hints = validate_pattern(pattern, lang)
  372. rewrite_hints = validate_pattern(rewrite, lang)
  373. all_hints = []
  374. if pattern_hints:
  375. all_hints.append("pattern issues:")
  376. all_hints.extend(f" - {h}" for h in pattern_hints)
  377. if rewrite_hints:
  378. all_hints.append("rewrite issues:")
  379. all_hints.extend(f" - {h}" for h in rewrite_hints)
  380. if all_hints:
  381. err("input looks invalid for ast-grep:")
  382. for line in all_hints:
  383. err(line)
  384. if not args.force:
  385. err("(pass --force to call ast-grep anyway)")
  386. return 2
  387. binary = require_binary()
  388. # Pass 1: dry-run via JSON to collect what would change.
  389. sg_args1 = ["run", "-p", pattern, "-r", rewrite, "--json=compact"]
  390. if lang:
  391. sg_args1.extend(["--lang", lang])
  392. for g in args.globs or []:
  393. sg_args1.extend(["--globs", g])
  394. sg_args1.extend(args.paths or ["."])
  395. proc1 = run_sg(binary, sg_args1)
  396. if proc1.returncode not in (0, 1):
  397. sys.stderr.write(proc1.stderr or "")
  398. return 4
  399. matches = parse_compact_json(proc1.stdout)
  400. if not matches:
  401. trace("no matches; nothing to replace.")
  402. return 0
  403. if not args.apply:
  404. # Show the dry-run preview and exit.
  405. print(f"DRY-RUN: would rewrite {len(matches)} match(es) across "
  406. f"{len({m['file'] for m in matches})} file(s):")
  407. format_matches(matches, show_replacement=True)
  408. print()
  409. print("Re-run with --apply to mutate files.")
  410. return 0
  411. # Pass 2: apply with --update-all (no --json; sg silently ignores --update-all
  412. # when --json is present, so we MUST run a second invocation).
  413. sg_args2 = ["run", "-p", pattern, "-r", rewrite, "--update-all"]
  414. if lang:
  415. sg_args2.extend(["--lang", lang])
  416. for g in args.globs or []:
  417. sg_args2.extend(["--globs", g])
  418. sg_args2.extend(args.paths or ["."])
  419. proc2 = run_sg(binary, sg_args2)
  420. if proc2.returncode not in (0, 1):
  421. sys.stderr.write(proc2.stderr or "")
  422. return 4
  423. print(f"APPLIED: rewrote {len(matches)} match(es) across "
  424. f"{len({m['file'] for m in matches})} file(s).")
  425. return 0
  426. def cmd_scan(args: argparse.Namespace) -> int:
  427. binary = require_binary()
  428. sg_args = ["scan"]
  429. if args.config:
  430. sg_args.extend(["-c", args.config])
  431. if args.rule:
  432. sg_args.extend(["-r", args.rule])
  433. if args.inline_rules:
  434. sg_args.extend(["--inline-rules", args.inline_rules])
  435. if args.report_style:
  436. sg_args.extend(["--report-style", args.report_style])
  437. if args.apply:
  438. sg_args.append("-U")
  439. sg_args.extend(args.paths or [])
  440. proc = run_sg(binary, sg_args, capture=False)
  441. return proc.returncode
  442. def cmd_test(args: argparse.Namespace) -> int:
  443. binary = require_binary()
  444. sg_args = ["test"]
  445. if args.config:
  446. sg_args.extend(["-c", args.config])
  447. if args.test_dir:
  448. sg_args.extend(["-t", args.test_dir])
  449. if args.update:
  450. sg_args.append("-U")
  451. proc = run_sg(binary, sg_args, capture=False)
  452. return proc.returncode
  453. def cmd_new(args: argparse.Namespace) -> int:
  454. binary = require_binary()
  455. sg_args = ["new", args.what]
  456. if args.name:
  457. sg_args.append(args.name)
  458. if args.lang:
  459. sg_args.extend(["--lang", args.lang])
  460. if args.yes:
  461. sg_args.append("--yes")
  462. proc = run_sg(binary, sg_args, capture=False)
  463. return proc.returncode
  464. def cmd_langs(_args: argparse.Namespace) -> int:
  465. print("ast-grep supported languages (25):")
  466. for lang, exts in sorted(LANGUAGES.items()):
  467. print(f" {lang:<12} {' '.join(exts)}")
  468. print()
  469. print("Aliases accepted by --lang:")
  470. for alias, canonical in sorted(LANG_ALIASES.items()):
  471. print(f" {alias:<8} -> {canonical}")
  472. return 0
  473. def cmd_doctor(_args: argparse.Namespace) -> int:
  474. print(f"ast-grep-helper v{VERSION}")
  475. print(f"Python: {sys.version.split()[0]}")
  476. print(f"Platform: {platform.system()} {platform.release()} ({platform.machine()})")
  477. print(f"Skill: {skill_root()}")
  478. print()
  479. binary = resolve_binary()
  480. if not binary:
  481. print("ast-grep binary: NOT FOUND")
  482. print(" -> run: bash install.sh (POSIX) or pwsh install.ps1 (Windows)")
  483. return 1
  484. print(f"ast-grep binary: {binary}")
  485. proc = run_sg(binary, ["--version"], timeout=5)
  486. if proc.returncode == 0:
  487. print(f" version: {proc.stdout.strip()}")
  488. else:
  489. print(f" --version returned exit {proc.returncode}")
  490. print(f" stderr: {proc.stderr.strip()}")
  491. return 1
  492. return 0
  493. def cmd_install(_args: argparse.Namespace) -> int:
  494. """Delegate to install.sh / install.ps1 in the skill root."""
  495. if os.name == "nt":
  496. installer = skill_root() / "install.ps1"
  497. cmd = ["pwsh", "-File", str(installer)]
  498. else:
  499. installer = skill_root() / "install.sh"
  500. cmd = ["bash", str(installer)]
  501. if not installer.is_file():
  502. err(f"installer not found: {installer}")
  503. return 1
  504. trace(f"running installer: {' '.join(cmd)}")
  505. # health: allow HX006 -- the installer downloads a release; its duration depends on the network
  506. return subprocess.run(cmd, stdin=subprocess.DEVNULL, check=False).returncode
  507. def cmd_validate(args: argparse.Namespace) -> int:
  508. """Offline pattern validation. No sg call. Useful for CI / quick checks."""
  509. lang = normalize_lang(args.lang) if args.lang else None
  510. hints = validate_pattern(args.pattern, lang)
  511. if hints:
  512. for h in hints:
  513. print(f"hint: {h}")
  514. return 2
  515. print("pattern looks plausible for ast-grep.")
  516. return 0
  517. # ---------- output formatting ----------
  518. def parse_compact_json(text: str) -> list[dict]:
  519. """Parse `sg --json=compact` output. Salvages partial output when truncated."""
  520. if not text.strip():
  521. return []
  522. try:
  523. data = json.loads(text)
  524. if isinstance(data, list):
  525. return data
  526. return []
  527. except json.JSONDecodeError:
  528. # Try line-by-line salvage for truncated output.
  529. results = []
  530. for line in text.splitlines():
  531. line = line.strip().rstrip(",")
  532. if not line.startswith("{"):
  533. continue
  534. try:
  535. obj = json.loads(line)
  536. if isinstance(obj, dict):
  537. results.append(obj)
  538. except json.JSONDecodeError:
  539. continue
  540. return results
  541. def format_matches(matches: list[dict], *, show_replacement: bool = False) -> None:
  542. if not matches:
  543. print("(no matches)")
  544. return
  545. by_file: dict[str, list[dict]] = {}
  546. for m in matches:
  547. by_file.setdefault(m.get("file", "?"), []).append(m)
  548. for path, items in sorted(by_file.items()):
  549. print(f"{path} ({len(items)} match{'es' if len(items) != 1 else ''})")
  550. for m in items:
  551. r = m.get("range", {})
  552. start = r.get("start", {})
  553. line = start.get("line", "?")
  554. col = start.get("column", "?")
  555. text = (m.get("text") or "").splitlines()
  556. preview = text[0] if text else ""
  557. print(f" {path}:{line}:{col} {preview}")
  558. if show_replacement and "replacement" in m:
  559. rep = (m.get("replacement") or "").splitlines()
  560. rep_preview = rep[0] if rep else ""
  561. print(f" -> {rep_preview}")
  562. # ---------- argparse ----------
  563. def build_parser() -> argparse.ArgumentParser:
  564. p = argparse.ArgumentParser(
  565. prog="ast-grep-helper",
  566. description="LLM-friendly wrapper around ast-grep (sg).",
  567. formatter_class=argparse.RawDescriptionHelpFormatter,
  568. )
  569. p.add_argument("--version", action="version", version=f"ast-grep-helper {VERSION}")
  570. p.add_argument("--quiet", "-q", action="store_true", help="Suppress trace lines on stderr.")
  571. sub = p.add_subparsers(dest="cmd", required=True, metavar="COMMAND")
  572. s = sub.add_parser("search", help="Search code by AST pattern.")
  573. s.add_argument("pattern", help="AST pattern, e.g. 'console.log($MSG)'")
  574. s.add_argument("paths", nargs="*", help="Paths to search (default: '.')")
  575. s.add_argument("--lang", "-l", help="Language (e.g. ts, py, go, rust). See: langs subcommand.")
  576. s.add_argument("--globs", action="append", help="Include/exclude glob (repeat; prefix '!' to exclude).")
  577. s.add_argument("--context", "-C", type=int, help="Lines of context around each match.")
  578. s.add_argument("--json-out", action="store_true", help="Emit raw JSON instead of human format.")
  579. s.add_argument("--force", action="store_true", help="Skip pattern hint validation.")
  580. s.set_defaults(func=cmd_search)
  581. r = sub.add_parser("replace", help="Rewrite code by AST pattern (dry-run by default).")
  582. r.add_argument("pattern", help="AST pattern.")
  583. r.add_argument("rewrite", help="Replacement pattern (can reuse $VAR from pattern).")
  584. r.add_argument("paths", nargs="*", help="Paths (default: '.')")
  585. r.add_argument("--lang", "-l", help="Language.")
  586. r.add_argument("--globs", action="append", help="Include/exclude glob.")
  587. r.add_argument("--apply", action="store_true", help="Mutate files (default: dry-run preview).")
  588. r.add_argument("--force", action="store_true", help="Skip pattern hint validation.")
  589. r.set_defaults(func=cmd_replace)
  590. sc = sub.add_parser("scan", help="Run YAML-rule-based scan.")
  591. sc.add_argument("paths", nargs="*", help="Paths to scan.")
  592. sc.add_argument("--config", "-c", help="Path to sgconfig.yml.")
  593. sc.add_argument("--rule", "-r", help="Single rule file.")
  594. sc.add_argument("--inline-rules", help="Inline YAML rule string.")
  595. sc.add_argument("--report-style", choices=["rich", "medium", "short"], help="Report style.")
  596. sc.add_argument("--apply", "-U", action="store_true", help="Apply fixes (default: report only).")
  597. sc.set_defaults(func=cmd_scan)
  598. t = sub.add_parser("test", help="Run ast-grep snapshot tests.")
  599. t.add_argument("--config", "-c", help="Path to sgconfig.yml.")
  600. t.add_argument("--test-dir", "-t", help="Test directory.")
  601. t.add_argument("--update", "-U", action="store_true", help="Update snapshots.")
  602. t.set_defaults(func=cmd_test)
  603. n = sub.add_parser("new", help="Scaffold a new project / rule / test / util.")
  604. n.add_argument("what", choices=["project", "rule", "test", "util"], help="What to create.")
  605. n.add_argument("name", nargs="?", help="Name of the artifact.")
  606. n.add_argument("--lang", "-l", help="Language.")
  607. n.add_argument("--yes", "-y", action="store_true", help="Accept defaults.")
  608. n.set_defaults(func=cmd_new)
  609. sub.add_parser("langs", help="List supported languages.").set_defaults(func=cmd_langs)
  610. sub.add_parser("doctor", help="Check ast-grep binary availability.").set_defaults(func=cmd_doctor)
  611. sub.add_parser("install", help="Run the install script for this OS.").set_defaults(func=cmd_install)
  612. v = sub.add_parser("validate", help="Validate a pattern offline (pattern hint check only).")
  613. v.add_argument("pattern", help="AST pattern.")
  614. v.add_argument("--lang", "-l", help="Language for language-specific hints.")
  615. v.set_defaults(func=cmd_validate)
  616. return p
  617. def main(argv: Optional[list[str]] = None) -> int:
  618. global _QUIET
  619. parser = build_parser()
  620. # Accept `search PATTERN --lang js .` — plain parse_args greedily
  621. # finalizes the nargs='*' paths list before the optional, then errors
  622. # "unrecognized arguments: ." on the trailing path.
  623. # parse_intermixed_args cannot be used with subparsers, so collect the
  624. # leftover non-flag tokens and fold them into `paths` ourselves.
  625. args, extras = parser.parse_known_args(argv)
  626. bad = [tok for tok in extras if tok.startswith("-")]
  627. if bad:
  628. parser.error(f"unrecognized arguments: {' '.join(bad)}")
  629. if extras:
  630. if hasattr(args, "paths"):
  631. args.paths = list(args.paths or []) + extras
  632. else:
  633. parser.error(f"unrecognized arguments: {' '.join(extras)}")
  634. _QUIET = bool(getattr(args, "quiet", False))
  635. return args.func(args)
  636. if __name__ == "__main__":
  637. sys.exit(main())