shellscriptor 0.1.0__py3-none-any.whl

shellscriptor/_script.py

@@ -0,0 +1,268 @@
+from __future__ import annotations
+
+from shellscriptor._argparse import (
+    create_argparse,
+    create_env_var_parse,
+    create_usage_function,
+)
+from shellscriptor._code import indent, sanitize_code
+from shellscriptor._log import log, log_endpoint
+from shellscriptor._output import create_output
+from shellscriptor._types import FunctionDef, ScriptDef, ScriptType
+from shellscriptor._validate import create_validation_block
+
+
+# ---------------------------------------------------------------------------
+# Cleanup function augmentation (internal)
+# ---------------------------------------------------------------------------
+
+
+def _augment_cleanup_function(data: FunctionDef | None) -> FunctionDef:
+    """Return a copy of *data* with logging/teardown lines appended to the body.
+
+    Only called for ``shell_exec`` scripts to ensure the ``__cleanup__``
+    trap handler flushes the captured log to ``$LOGFILE`` if set.
+
+    Parameters
+    ----------
+    data:
+        Existing function definition, or ``None`` for a new one.
+
+    Returns
+    -------
+    A new ``FunctionDef`` (never mutates *data*).
+    """
+    body_lines = list(data.body) if data else []
+    log_cleanup_lines = [
+        'if [ -n "${LOGFILE-}" ]; then',
+        indent("exec 1>&3 2>&4", 1),   # restore original stdout/stderr
+        indent("wait 2>/dev/null", 1),  # let tee flush
+        indent(log("Write logs to file '$LOGFILE'", "info"), 1),
+        indent('mkdir -p "$(dirname "$LOGFILE")"', 1),
+        indent('cat "$_LOGFILE_TMP" >> "$LOGFILE"', 1),
+        indent('rm -f "$_LOGFILE_TMP"', 1),
+        "fi",
+    ]
+    body_lines.extend(log_cleanup_lines)
+    if data is None:
+        return FunctionDef(body=body_lines)
+    return data.model_copy(update={"body": body_lines})
+
+
+# ---------------------------------------------------------------------------
+# Function generator
+# ---------------------------------------------------------------------------
+
+
+def create_function(
+    name: str,
+    data: dict | FunctionDef,
+    script_type: ScriptType,
+) -> list[str]:
+    """Generate a complete shell function definition.
+
+    Parameters
+    ----------
+    name:
+        Function name.
+    data:
+        Function definition dict or :class:`~shellscriptor._types.FunctionDef`
+        model.  Recognised input keys: ``"parameter"``, ``"body"``,
+        ``"return"`` / ``"return_"``.
+    script_type:
+        Controls log call emission.
+
+    Returns
+    -------
+    Lines defining ``name() { … }``.
+    """
+    if isinstance(data, dict):
+        data = FunctionDef.model_validate(data)
+
+    parameters = data.parameter or None
+
+    body_lines: list[str] = []
+    if script_type == "shell_exec":
+        body_lines.append(log_endpoint(name, typ="function", stage="entry"))
+
+    if parameters:
+        usage_lines = create_usage_function(parameters)
+        body_lines.extend(usage_lines)
+        body_lines.extend(
+            create_argparse(
+                parameters,
+                local=True,
+                script_type=script_type,
+                with_help=bool(usage_lines),
+            )
+        )
+        body_lines.extend(
+            create_validation_block(parameters, local=True, script_type=script_type)
+        )
+
+    body_lines.extend(sanitize_code(data.body))
+    body_lines.extend(create_output(data.returns, script_type=script_type))
+
+    if script_type == "shell_exec":
+        body_lines.append(log_endpoint(name, typ="function", stage="exit"))
+
+    return [f"{name}() {{", *indent(body_lines, 1), "}"]
+
+
+# ---------------------------------------------------------------------------
+# Script generator
+# ---------------------------------------------------------------------------
+
+
+def create_script(
+    name: str,
+    data: dict | ScriptDef,
+    script_type: ScriptType,
+    global_functions: dict | None = None,
+) -> str:
+    """Generate a complete shell script from a definition dict.
+
+    Parameters
+    ----------
+    name:
+        Script name (used in log messages).
+    data:
+        Script definition.  Recognised keys:
+
+        * ``"interpreter"`` — shebang path (``str``).
+        * ``"flags"`` — ``set`` flags string (e.g. ``"-euo pipefail"``).
+        * ``"import"`` / ``"import_"`` — list of global function names to include.
+        * ``"function"`` — ``dict[str, FunctionDef]`` of locally defined functions.
+        * ``"parameter"`` — ``dict[str, ParameterDef]``.
+        * ``"body"`` — script body (``str | list[str] | list[BodySection]``).
+        * ``"return"`` / ``"return_"`` — ``list[ReturnDef]``.
+    script_type:
+        ``"shell_src"`` — library script (no boilerplate).
+        ``"shell_exec"`` — executable script (tee logging, trap, arg parsing).
+    global_functions:
+        Pool of reusable function definitions; only those listed in
+        ``data["import"]`` are included.
+
+    Returns
+    -------
+    Generated script as a single string.
+    """
+    if isinstance(data, dict):
+        data = ScriptDef.model_validate(data)
+
+    lines: list[str] = []
+
+    # Shebang
+    if data.interpreter:
+        lines.append(
+            "#!/" + data.interpreter.removeprefix("#").removeprefix("!").removeprefix("/")
+        )
+
+    # set flags
+    if data.flags:
+        lines.append(f"set {data.flags}")
+
+    # Collect functions: imported globals + locally defined
+    functions: dict[str, FunctionDef] = {
+        fn: FunctionDef.model_validate(fd) if isinstance(fd, dict) else fd
+        for fn, fd in (global_functions or {}).items()
+        if fn in data.imports
+    }
+    functions.update(data.function)
+
+    # shell_exec: inject/augment __cleanup__
+    if script_type == "shell_exec":
+        functions["__cleanup__"] = _augment_cleanup_function(
+            functions.get("__cleanup__")
+        )
+
+    # Emit function definitions separated by blank lines (F7)
+    func_blocks: list[list[str]] = [
+        create_function(fn, fd, script_type)
+        for fn, fd in sorted(functions.items())
+    ]
+    # Auto-generate __usage__ if any parameters have descriptions
+    parameters = data.parameter or None
+    _with_help = False
+    if parameters:
+        usage_lines = create_usage_function(parameters)
+        if usage_lines:
+            func_blocks.insert(0, usage_lines)
+        _with_help = bool(usage_lines)
+
+    for block in func_blocks:
+        lines.extend(block)
+        lines.append("")  # F7: blank line between functions
+
+    # shell_exec boilerplate: log capture setup + trap
+    if script_type == "shell_exec":
+        lines.extend(
+            [
+                '_LOGFILE_TMP="$(mktemp)"',
+                "exec 3>&1 4>&2",
+                'exec > >(tee -a "$_LOGFILE_TMP" >&3) 2>&1',
+                log_endpoint(name, typ="script", stage="entry"),
+                "trap __cleanup__ EXIT",
+            ]
+        )
+
+    # Argument / env-var parsing + validation
+    if parameters:
+        if script_type == "shell_exec":
+            lines.extend(
+                [
+                    'if [ "$#" -gt 0 ]; then',
+                    indent(log("Script called with arguments: $@", "info"), 1),
+                    *indent(
+                        create_argparse(
+                            parameters,
+                            local=False,
+                            script_type=script_type,
+                            with_help=_with_help,
+                        ),
+                        1,
+                    ),
+                    "else",
+                    indent(
+                        log(
+                            "Script called with no arguments. Read environment variables.",
+                            "info",
+                        ),
+                        1,
+                    ),
+                    *indent(create_env_var_parse(parameters), 1),
+                    "fi",
+                    '[[ "$DEBUG" == true ]] && set -x',
+                    *create_validation_block(
+                        parameters, local=False, script_type=script_type
+                    ),
+                ]
+            )
+        else:
+            # shell_src: still parse args if defined
+            lines.extend(
+                create_argparse(
+                    parameters,
+                    local=False,
+                    script_type=script_type,
+                    with_help=_with_help,
+                )
+            )
+            lines.extend(
+                create_validation_block(
+                    parameters, local=False, script_type=script_type
+                )
+            )
+
+    # Body
+    lines.extend(sanitize_code(data.body))
+
+    # Output / return
+    if script_type == "shell_exec" and data.returns:
+        lines.extend(create_output(data.returns, script_type=script_type))
+
+    # Exit log
+    if script_type == "shell_exec":
+        lines.append(log_endpoint(name, typ="script", stage="exit"))
+
+    return "\n".join(lines)

shellscriptor/_types.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, model_validator
+from typing import Annotated
+from pydantic.functional_validators import BeforeValidator
+
+
+# ---------------------------------------------------------------------------
+# Primitive type aliases
+# ---------------------------------------------------------------------------
+
+ScriptType = Literal["shell_src", "shell_exec"]
+"""Whether the script is a sourced library or a directly executed script."""
+
+ParamType = Literal["string", "boolean", "array", "integer"]
+"""Supported parameter/variable types."""
+
+PathType = Literal["dir", "exec", "file", "symlink"]
+"""Path kinds for path-existence validation."""
+
+LogLevel = Literal["info", "warn", "error", "critical"]
+"""Severity levels for generated log statements."""
+
+
+# ---------------------------------------------------------------------------
+# Body normalisation (runs at validation time)
+# ---------------------------------------------------------------------------
+
+
+def _normalize_body_input(v: Any) -> list[str]:
+    """Normalise any accepted body form to a flat list of strings.
+
+    Accepted forms: ``str``, ``list[str]``, ``list[dict]`` (each dict must
+    have a ``"content"`` key), ``list[BodySection]``, or any object with a
+    ``content`` attribute.
+    """
+    if not v:
+        return []
+    if isinstance(v, str):
+        return v.splitlines()
+    if isinstance(v, list):
+        lines: list[str] = []
+        for item in v:
+            if isinstance(item, str):
+                lines.append(item)
+            elif isinstance(item, dict):
+                lines.extend(item.get("content", "").splitlines())
+            else:
+                lines.extend(str(getattr(item, "content", "")).splitlines())
+        return lines
+    raise ValueError(f"Unsupported body type: {type(v)!r}")
+
+
+_Body = Annotated[list[str], BeforeValidator(_normalize_body_input)]
+
+
+# ---------------------------------------------------------------------------
+# Validation sub-models
+# ---------------------------------------------------------------------------
+
+
+class PathExistenceDef(BaseModel):
+    """Validation rule: assert that a path exists (or does not exist)."""
+
+    must_exist: bool = Field(
+        description="When true the path must exist; when false it must not exist.",
+    )
+    type: PathType | None = Field(
+        default=None,
+        description=(
+            "Kind of filesystem entry to test. "
+            "One of 'dir', 'exec', 'file', 'symlink', or null to accept any entry."
+        ),
+    )
+
+
+class IntegerRangeDef(BaseModel):
+    """Validation rule: assert that an integer falls within a numeric range."""
+
+    min: int | None = Field(
+        default=None,
+        description="Inclusive lower bound. Omit or set to null for no lower bound.",
+    )
+    max: int | None = Field(
+        default=None,
+        description="Inclusive upper bound. Omit or set to null for no upper bound.",
+    )
+
+    @model_validator(mode="after")
+    def _check_range_order(self) -> "IntegerRangeDef":
+        """Ensure min <= max when both bounds are provided."""
+        if self.min is not None and self.max is not None and self.min > self.max:
+            raise ValueError(
+                f"IntegerRangeDef: min ({self.min}) must be <= max ({self.max})"
+            )
+        return self
+
+
+class ValidationDef(BaseModel):
+    """Validation rules for a single parameter."""
+
+    enum: list[str] = Field(
+        default_factory=list,
+        description="Exhaustive list of accepted values. Rejected values cause a fatal error.",
+    )
+    path_existence: PathExistenceDef | None = Field(
+        default=None,
+        description="Assert that the value is a path that exists (or does not exist).",
+    )
+    integer_range: IntegerRangeDef | None = Field(
+        default=None,
+        description="Assert that the integer value falls within an inclusive numeric range.",
+    )
+    regex: str | None = Field(
+        default=None,
+        description="ERE pattern the value must match in full. Rejection is fatal.",
+    )
+    custom: list[str] = Field(
+        default_factory=list,
+        description="Verbatim shell lines appended after all other validation checks.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Parameter / return / function / script models
+# ---------------------------------------------------------------------------
+
+
+class ParameterDef(BaseModel):
+    """Definition of a single script/function parameter."""
+
+    type: ParamType = Field(
+        description="Shell type of the parameter: 'string', 'boolean', 'array', or 'integer'.",
+    )
+    default: str | list[str] | None = Field(
+        default=None,
+        description=(
+            "Default value applied when the argument is absent. "
+            "Use a list for array-typed parameters. "
+            "Omit or set to null to make the parameter required."
+        ),
+    )
+    required: bool | None = Field(
+        default=None,
+        description=(
+            "Explicit required flag. When null, the parameter is considered required "
+            "if and only if 'default' is also null."
+        ),
+    )
+    description: str = Field(
+        default="",
+        description=(
+            "Human-readable description shown in the auto-generated --help output. "
+            "Triggers --help / __usage__ generation when non-empty on any parameter."
+        ),
+    )
+    short: str = Field(
+        default="",
+        description=(
+            "Single-character short flag alias (without the leading dash). "
+            "For example 'n' generates a '-n' arm alongside '--<param-name>'."
+        ),
+    )
+    array_delimiter: str = Field(
+        default=" ",
+        description=(
+            "Delimiter used when reading an array parameter from a single environment "
+            "variable (env-var fallback path). Defaults to a single space."
+        ),
+    )
+    validation: ValidationDef | None = Field(
+        default=None,
+        description="Optional set of validation rules applied after argument parsing.",
+    )
+
+
+class ReturnDef(BaseModel):
+    """Definition of a single return value."""
+
+    name: str = Field(
+        description="Human-readable label for the return value, used in log messages.",
+    )
+    variable: str = Field(
+        description="Name of the shell variable whose value is written to stdout.",
+    )
+    type: ParamType = Field(
+        description="Type of the return value; drives the output encoding scheme.",
+    )
+
+
+class BodySection(BaseModel):
+    """A single body section (the dict form used in script/function definitions)."""
+
+    content: str = Field(
+        description="Raw shell code for this section. May contain newlines.",
+    )
+
+
+class FunctionDef(BaseModel):
+    """Definition of a shell function."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    parameter: dict[str, ParameterDef] = Field(
+        default_factory=dict,
+        description="Named parameters accepted by this function, keyed by parameter name.",
+    )
+    body: _Body = Field(
+        default_factory=list,
+        description=(
+            "Shell code forming the function body. "
+            "Accepts a plain string, a list of strings, or a list of {content: ...} objects."
+        ),
+    )
+    returns: list[ReturnDef] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("return", "return_"),
+        description="Values written to stdout when the function exits.",
+    )
+
+
+class ScriptDef(BaseModel):
+    """Top-level script definition."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    interpreter: str | None = Field(
+        default=None,
+        description=(
+            "Interpreter path written as the shebang line (without the leading '#!'). "
+            "For example 'usr/bin/env bash' produces '#!/usr/bin/env bash'. "
+            "Omit to produce a script with no shebang."
+        ),
+    )
+    flags: str | None = Field(
+        default=None,
+        description=(
+            "Argument string passed to 'set' immediately after the shebang. "
+            "For example '-euo pipefail'."
+        ),
+    )
+    imports: list[str] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("import", "import_"),
+        description=(
+            "Names of functions from the global_functions pool to include verbatim "
+            "in this script."
+        ),
+    )
+    function: dict[str, FunctionDef] = Field(
+        default_factory=dict,
+        description="Local function definitions, keyed by function name.",
+    )
+    parameter: dict[str, ParameterDef] = Field(
+        default_factory=dict,
+        description="Script-level parameters accepted on the command line or from environment variables.",
+    )
+    body: _Body = Field(
+        default_factory=list,
+        description=(
+            "Main script body executed after argument parsing and validation. "
+            "Accepts a plain string, a list of strings, or a list of {content: ...} objects."
+        ),
+    )
+    returns: list[ReturnDef] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("return", "return_"),
+        description="Values written to stdout before the script exits (shell_exec only).",
+    )