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
298 lines
8.8 KiB
Python
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
|