kuri-tool-guard/_parser.py
XLion 06a7f93d18
refactor(kuri-tool-guard): modularise monolithic __init__.py and tests
Split the 1341-line __init__.py into 5 focused modules:
  _state.py    - home root helpers, mutable poll state
  _parser.py   - shell tokenizer (independent)
  _predicates.py - terminal predicates + bounded output
  _guards.py   - all 9 guard implementations + AST helpers
  __init__.py  - thin entry point + dispatcher + re-exports

Split the 2226-line test_guard.py into 14 dedicated files:
  13 test_*.py files + tests/_support.py (shared helpers)

Key changes:
- Package-relative imports throughout (Hermes loader compatible)
- No top-level module pollution (hermes_plugins.kuri_tool_guard.* only)
- Typechecked via ty with symlink alias for hyphenated dir name
- All 10 guard policies, messages, and block/allow behaviour preserved
- 338 tests (336 original + 2 new: isolation + loader contract)
- ty, ruff, bandit, vulture all pass in just verify
2026-07-31 02:23:02 +08:00

298 lines
8.8 KiB
Python

"""kuri-tool-guard — shell tokenization and parser helpers.
Independent module with no dependencies on other kuri-tool-guard modules.
"""
from __future__ import annotations
import os
import re
import shlex
# ── Wrapper / option / pattern constants ─────────────────────────
_WRAPPER_COMMANDS: frozenset[str] = frozenset({"command", "env", "time", "nice", "nohup"})
_WRAPPER_OPTIONS_WITH_ARG: dict[str, frozenset[str]] = {
"nice": frozenset({"-n", "--adjustment"}),
"env": frozenset({"-u", "--unset"}),
"time": frozenset({"-f", "--format"}),
}
_STRIP_QUOTES = re.compile(r"'[^']*'|\"[^\"]*\"")
_DEVNULL = re.compile(r"^/dev/null$")
# ── Quote/escape-aware operator splitters ────────────────────────
def _skip_quoted(text: str, i: int, n: int, quote: str) -> int:
i += 1
while i < n and text[i] != quote:
if text[i] == "\\" and i + 1 < n:
i += 2
else:
i += 1
return i + 1 if i < n else i
def _split_chain_segments(text: str) -> list[str]:
parts: list[str] = []
seg_start = 0
i = 0
n = len(text)
chain_ops: frozenset[str] = frozenset({";", "&&", "||", "\n"})
while i < n:
c = text[i]
if c in ("'", '"'):
i = _skip_quoted(text, i, n, c)
elif c == "\\" and i + 1 < n:
i += 2
else:
matched: str | None = None
for op_len in (2, 1):
if i + op_len <= n and text[i : i + op_len] in chain_ops:
matched = text[i : i + op_len]
break
if matched:
seg = text[seg_start:i].strip()
if seg:
parts.append(seg)
i += len(matched)
seg_start = i
else:
i += 1
seg = text[seg_start:].strip()
if seg:
parts.append(seg)
return parts
def _split_pipe_commands(segment: str) -> list[str]:
parts: list[str] = []
seg_start = 0
i = 0
n = len(segment)
pipe_ops: frozenset[str] = frozenset({"|&", "|"})
while i < n:
c = segment[i]
if c in ("'", '"'):
i = _skip_quoted(segment, i, n, c)
elif c == "\\" and i + 1 < n:
i += 2
else:
matched: str | None = None
for op_len in (2, 1):
if i + op_len <= n and segment[i : i + op_len] in pipe_ops:
matched = segment[i : i + op_len]
break
if matched:
seg = segment[seg_start:i].strip()
if seg:
parts.append(seg)
i += len(matched)
seg_start = i
else:
i += 1
seg = segment[seg_start:].strip()
if seg:
parts.append(seg)
return parts
# ── Helpers ──────────────────────────────────────────────────────
def _is_assignment(token: str) -> bool:
return "=" in token and not token.startswith("-")
def _first_command_token_index(tokens: list[str]) -> int:
i = 0
while i < len(tokens):
t = tokens[i]
if _is_assignment(t):
i += 1
continue
if t in _WRAPPER_COMMANDS:
i += 1
while i < len(tokens):
nt = tokens[i]
if _is_assignment(nt):
i += 1
continue
if t == "command" and nt in ("-v", "-V"):
i += 2
continue
if nt.startswith("-"):
opt_key = nt.split("=")[0]
wrapper_opts = _WRAPPER_OPTIONS_WITH_ARG.get(t, frozenset())
consumes = opt_key in wrapper_opts and "=" not in nt
i += 1
if consumes and i < len(tokens):
i += 1
continue
break
continue
break
return i
def _is_cat_command(tokens: list[str]) -> bool:
idx = _first_command_token_index(tokens)
return idx < len(tokens) and os.path.basename(tokens[idx]) == "cat"
def _unquote_shell_token(token: str) -> str:
if len(token) < 2 or token[0] != token[-1]:
return token
if token[0] == "'":
return token[1:-1]
if token[0] == '"':
inner = token[1:-1]
result: list[str] = []
i = 0
while i < len(inner):
if inner[i] == "\\" and i + 1 < len(inner):
result.append(inner[i + 1])
i += 2
else:
result.append(inner[i])
i += 1
return "".join(result)
return token
# ── Process substitution / here-string scanning ──────────────────
def _skip_process_substitution(text: str, i: int, n: int) -> int:
if i + 1 < n and text[i + 1] == "(":
depth = 1
i += 2
while i < n and depth > 0:
c = text[i]
if c == "(":
depth += 1
elif c == ")":
depth -= 1
elif c in ("'", '"'):
i = _skip_quoted(text, i, n, c)
continue
i += 1
return i
def _skip_here_string(text: str, i: int, n: int) -> int:
i += 3
if i < n and text[i] in ("'", '"'):
i = _skip_quoted(text, i, n, text[i])
else:
while i < n and not text[i].isspace() and text[i] not in (";", "|", "&", ">", "<"):
i += 1
return i
# ── Redirect scanning ────────────────────────────────────────────
def _scan_redirect_target(text: str, i: int, n: int) -> tuple[int, str]:
if i < n and text[i] in ("'", '"'):
q = text[i]
new_i = _skip_quoted(text, i, n, q)
return new_i, text[i:new_i]
if i < n and text[i] == ">" and i + 1 < n and text[i + 1] == "(":
new_i = _skip_process_substitution(text, i, n)
return new_i, text[i:new_i]
start = i
while i < n and not text[i].isspace() and text[i] not in (";", "|", ">", "<", ")"):
i += 1
return i, text[start:i]
def _iter_redirects(text: str):
i = 0
n = len(text)
while i < n:
c = text[i]
if c in ("'", '"'):
i = _skip_quoted(text, i, n, c)
elif c == "\\" and i + 1 < n:
i += 2
elif c == "<" and i + 1 < n and text[i + 1] == "(":
i = _skip_process_substitution(text, i, n)
elif c == "<" and i + 2 < n and text[i : i + 3] == "<<<":
i = _skip_here_string(text, i, n)
elif c == "<":
i += 1
elif c == ">":
if i + 1 < n and text[i + 1] == "(":
i = _skip_process_substitution(text, i, n)
continue
prefix_end = i
while prefix_end > 0 and text[prefix_end - 1] in "0123456789&":
prefix_end -= 1
prefix = text[prefix_end:i] if prefix_end < i else ""
operator = ">"
i += 1
if i < n and text[i] == ">":
operator = ">>"
i += 1
while i < n and text[i].isspace():
i += 1
i, raw_target = _scan_redirect_target(text, i, n)
unquoted = _unquote_shell_token(raw_target)
yield (prefix, operator, unquoted)
else:
i += 1
def _stdout_destination(scmd_text: str) -> str:
result = "terminal"
for prefix, _op, target in _iter_redirects(scmd_text):
if prefix.isdigit() and prefix != "1" and "&" not in prefix:
continue
if target.startswith("&"):
result = "fd"
elif target.startswith(">("):
result = "subst"
elif target == "/dev/null":
result = "devnull"
else:
result = "file"
return result
def _has_file_write(cmd_text: str) -> bool:
for _prefix, _op, target in _iter_redirects(cmd_text):
if target.startswith("&"):
continue
if target.startswith(">("):
continue
if target == "/dev/null":
continue
return True
return False
# ── Command-level token splitter ─────────────────────────────────
def _get_command_tokens(command: str) -> list[list[str]]:
all_tokens: list[list[str]] = []
segs = _split_chain_segments(command)
for seg in segs:
pipes = _split_pipe_commands(seg)
for pipe_cmd in pipes:
try:
tokens = shlex.split(pipe_cmd)
except ValueError:
continue
if tokens:
all_tokens.append(tokens)
return all_tokens