python-yama 0.1.0__py3-none-any.whl

yama/tools/bash/bash.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+import yaml
+
+from ..base import Tool
+from ...mocks import MockConfigurationError, ToolMockContext, ToolMockError
+from .fs import run_bash_cli, run_bash_fs
+
+_RULE_FIELDS = {"match", "stdout", "stderr", "exit_code", "passthrough"}
+_NODE_FIELDS = {"description", "rules", "commands", "default"}
+_SPEC_FIELDS = _NODE_FIELDS | {"name"}
+_MATCH_FIELDS = {"argv", "argline"}
+_RESERVED_CLI_FIELDS = {"passthrough", "passthrough_timeout_seconds"}
+DEFAULT_PASSTHROUGH_TIMEOUT_SECONDS = 30.0
+
+# normalize_cli_config only validates and shapes the declarative mocks.cli
+# schema. Execution has moved to fs: each mocked command is compiled
+# into a real, PATH-shadowed shell script running in a sandboxed workspace
+# (see fs.compile_cli_config and yama.tools.bash._cli_shim) instead of being
+# interpreted by a hand-rolled bash tokenizer/parser here.
+
+
+def normalize_cli_config(
+    cli: Any,
+    *,
+    base_dir: Path | None = None,
+    root: Path | None = None,
+) -> dict[str, Any]:
+    if cli is None:
+        cli = {}
+    if not isinstance(cli, dict):
+        raise MockConfigurationError("mocks.cli must be an object")
+    passthrough = cli.get("passthrough", False)
+    if not isinstance(passthrough, bool):
+        raise MockConfigurationError("mocks.cli.passthrough must be a boolean")
+    timeout = cli.get("passthrough_timeout_seconds", DEFAULT_PASSTHROUGH_TIMEOUT_SECONDS)
+    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or timeout <= 0:
+        raise MockConfigurationError(
+            "mocks.cli.passthrough_timeout_seconds must be a positive number"
+        )
+    normalized: dict[str, Any] = {
+        "passthrough": passthrough,
+        "passthrough_timeout_seconds": float(timeout),
+    }
+    for name, value in cli.items():
+        if name in _RESERVED_CLI_FIELDS:
+            continue
+        _validate_command_name(name, "mocks.cli")
+        normalized[name] = _normalize_node(
+            value,
+            label=f"mocks.cli.{name}",
+            base_dir=base_dir,
+            root=root,
+            file_name=name,
+        )
+    return normalized
+
+
+def _validate_command_name(name: Any, label: str) -> None:
+    if not isinstance(name, str) or not name.strip() or " " in name:
+        raise MockConfigurationError(
+            f"{label} command names must be single words: {name!r}"
+        )
+
+
+def _normalize_node(
+    value: Any,
+    *,
+    label: str,
+    base_dir: Path | None,
+    root: Path | None,
+    file_name: str | None = None,
+) -> dict[str, Any]:
+    if isinstance(value, str):
+        return {
+            "rules": [],
+            "commands": {},
+            "default": _normalize_rule(label, {"stdout": value}),
+        }
+    if isinstance(value, list) and value:
+        return {
+            "rules": [_normalize_rule(label, rule) for rule in value],
+            "commands": {},
+            "default": None,
+        }
+    if not isinstance(value, dict) or not value:
+        raise MockConfigurationError(
+            f"{label} must be a string, a non-empty object or a non-empty list"
+        )
+    keys = set(value)
+    if "file" in keys:
+        if file_name is None:
+            raise MockConfigurationError(
+                f"{label} cannot use nested file references"
+            )
+        if keys != {"file"}:
+            raise MockConfigurationError(
+                f"{label} file entries cannot contain other fields"
+            )
+        return _normalize_spec_file(
+            value["file"],
+            label=label,
+            base_dir=base_dir,
+            root=root,
+            expected_name=file_name,
+        )
+    if keys <= _RULE_FIELDS:
+        return {
+            "rules": [_normalize_rule(label, value)],
+            "commands": {},
+            "default": None,
+        }
+    if not keys <= _NODE_FIELDS:
+        unknown = keys - (_NODE_FIELDS | _RULE_FIELDS)
+        if unknown:
+            raise MockConfigurationError(
+                f"unknown {label} fields: {sorted(unknown)}"
+            )
+        raise MockConfigurationError(
+            f"{label} cannot mix rule fields {sorted(keys & _RULE_FIELDS)} "
+            f"with {sorted(keys & _NODE_FIELDS)}"
+        )
+    return _normalize_node_fields(value, label=label, base_dir=base_dir, root=root)
+
+
+def _normalize_node_fields(
+    value: dict[str, Any],
+    *,
+    label: str,
+    base_dir: Path | None,
+    root: Path | None,
+) -> dict[str, Any]:
+    description = value.get("description")
+    if description is not None and not isinstance(description, str):
+        raise MockConfigurationError(f"{label} description must be a string")
+    rules_value = value.get("rules") or []
+    if not isinstance(rules_value, list):
+        raise MockConfigurationError(f"{label} rules must be a list")
+    rules = [_normalize_rule(label, rule) for rule in rules_value]
+    commands_value = value.get("commands") or {}
+    if not isinstance(commands_value, dict):
+        raise MockConfigurationError(f"{label} commands must be an object")
+    commands: dict[str, dict[str, Any]] = {}
+    for sub, sub_value in commands_value.items():
+        _validate_command_name(sub, f"{label}.commands")
+        commands[sub] = _normalize_node(
+            sub_value,
+            label=f"{label}.commands.{sub}",
+            base_dir=base_dir,
+            root=root,
+        )
+    default_value = value.get("default")
+    default = None
+    if default_value is not None:
+        if isinstance(default_value, str):
+            default_value = {"stdout": default_value}
+        default = _normalize_rule(f"{label}.default", default_value)
+        if default["match"]:
+            raise MockConfigurationError(
+                f"{label}.default cannot use match; add a rule instead"
+            )
+    if not rules and not commands and default is None:
+        raise MockConfigurationError(
+            f"{label} must declare rules, commands or default"
+        )
+    return {"rules": rules, "commands": commands, "default": default}
+
+
+def _normalize_spec_file(
+    reference: Any,
+    *,
+    label: str,
+    base_dir: Path | None,
+    root: Path | None,
+    expected_name: str,
+) -> dict[str, Any]:
+    if not isinstance(reference, str) or not reference.strip():
+        raise MockConfigurationError(f"{label} file must be a relative path")
+    if base_dir is None:
+        raise MockConfigurationError(
+            f"{label} file references are only supported in mocks.cli"
+        )
+    path = (Path(base_dir) / reference).resolve()
+    boundary = Path(root or base_dir).resolve()
+    if not path.is_relative_to(boundary):
+        raise MockConfigurationError(
+            f"cli mock file must be inside the plugin: {path}"
+        )
+    if path.suffix not in {".yaml", ".yml"}:
+        raise MockConfigurationError(f"cli mock file must be YAML: {path}")
+    if not path.is_file():
+        raise MockConfigurationError(f"cli mock file does not exist: {path}")
+    try:
+        spec = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError) as exc:
+        raise MockConfigurationError(
+            f"cannot load cli mock file {path}: {exc}"
+        ) from exc
+    if not isinstance(spec, dict):
+        raise MockConfigurationError(f"cli mock file root must be an object: {path}")
+    unknown = set(spec) - _SPEC_FIELDS
+    if unknown:
+        raise MockConfigurationError(
+            f"unknown cli mock file fields in {path.name}: {sorted(unknown)}"
+        )
+    name = spec.get("name")
+    if name != expected_name:
+        raise MockConfigurationError(
+            f"cli mock name mismatch: {label} expects {expected_name!r}, "
+            f"{path.name} has {name!r}"
+        )
+    node = {key: item for key, item in spec.items() if key in _NODE_FIELDS}
+    return _normalize_node_fields(
+        node,
+        label=f"{label} ({path.name})",
+        base_dir=base_dir,
+        root=root,
+    )
+
+
+def _normalize_rule(label: str, rule: Any) -> dict[str, Any]:
+    if isinstance(rule, str):
+        rule = {"stdout": rule}
+    if not isinstance(rule, dict):
+        raise MockConfigurationError(f"{label} rules must be strings or objects")
+    unknown = set(rule) - _RULE_FIELDS
+    if unknown:
+        raise MockConfigurationError(
+            f"unknown {label} rule fields: {sorted(unknown)}"
+        )
+    match = rule.get("match", {})
+    if not isinstance(match, dict):
+        raise MockConfigurationError(f"{label} match must be an object")
+    unknown = set(match) - _MATCH_FIELDS
+    if unknown:
+        raise MockConfigurationError(
+            f"{label} match only supports argv and argline: {sorted(unknown)}"
+        )
+    passthrough = rule.get("passthrough", False)
+    if not isinstance(passthrough, bool):
+        raise MockConfigurationError(f"{label} passthrough must be a boolean")
+    stdout = rule.get("stdout", "")
+    stderr = rule.get("stderr", "")
+    exit_code = rule.get("exit_code", 0)
+    non_default_outputs = [
+        key
+        for key, value in (("stdout", stdout), ("stderr", stderr), ("exit_code", exit_code))
+        if value not in ("", 0)
+    ]
+    if passthrough and non_default_outputs:
+        raise MockConfigurationError(
+            f"{label} cannot combine passthrough with {sorted(non_default_outputs)}"
+        )
+    if not isinstance(stdout, str) or not isinstance(stderr, str):
+        raise MockConfigurationError(f"{label} stdout and stderr must be strings")
+    if isinstance(exit_code, bool) or not isinstance(exit_code, int):
+        raise MockConfigurationError(f"{label} exit_code must be an integer")
+    return {
+        "match": match,
+        "passthrough": passthrough,
+        "stdout": stdout,
+        "stderr": stderr,
+        "exit_code": exit_code,
+    }
+
+
+class BashTool(Tool):
+    async def run(
+        self,
+        arguments: Mapping[str, Any],
+        context: ToolMockContext | None,
+        config: Mapping[str, Any],
+    ) -> dict[str, Any]:
+        command = arguments.get("command")
+        if not isinstance(command, str) or not command.strip():
+            raise ToolMockError("INVALID_COMMAND", "command must be a non-empty string")
+        if "fs" in config:
+            return await run_bash_fs(arguments, context, config["fs"])
+        return await run_bash_cli(arguments, context, config.get("cli", {}))
+
+
+run_bash = BashTool().run