patchahead 0.3.0__py3-none-any.whl

patchahead/apidiff/surface.py

@@ -0,0 +1,337 @@
+"""The public API of a Python library, read from its source without running it.
+
+A library is parsed, never imported: importing runs its code, and the point of
+reading two versions side by side is to do it before trusting either. What is
+recorded is what a caller can depend on -- public functions, classes, methods,
+and each parameter's name, kind, position, and whether it has a default.
+
+"Public" follows the conventions a caller relies on: a name without a leading
+underscore, in a module whose path has no private component, filtered by
+``__all__`` where a module declares one -- plus anything a public module
+re-exports with ``from .impl import Name``, which is how most libraries expose
+code that lives in private modules.
+"""
+
+from __future__ import annotations
+
+import ast
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from patchahead.analysis.edits import read_source
+
+log = logging.getLogger(__name__)
+
+#: Directories in a source tree or wheel that are not the library's code.
+_SKIP_DIRS = {"tests", "test", "testing", "docs", "examples", "benchmarks"}
+
+
+@dataclass(frozen=True)
+class Param:
+    """One parameter, as a caller sees it."""
+
+    name: str
+    #: ``positional`` (positional-only), ``normal``, ``var_positional``,
+    #: ``keyword`` (keyword-only), or ``var_keyword``.
+    kind: str
+    has_default: bool
+
+    def render(self) -> str:
+        prefix = {"var_positional": "*", "var_keyword": "**"}.get(self.kind, "")
+        return f"{prefix}{self.name}{'=...' if self.has_default else ''}"
+
+
+@dataclass
+class Member:
+    """A public function, class, or method, where it is defined."""
+
+    #: Dotted module the definition lives in, e.g. ``storekit._client``.
+    module: str
+    #: ``fetch_all`` for a function, ``Client`` for a class, ``Client.fetch_all``
+    #: for a method.
+    qualname: str
+    kind: str  # "function" | "class" | "method"
+    params: tuple[Param, ...] = ()
+    #: For a class: its public method names, used to recognize a renamed class.
+    methods: frozenset[str] = frozenset()
+    #: Marked deprecated: a ``@deprecated`` decorator, or a deprecation warning.
+    deprecated: bool = False
+    #: The sibling a deprecated member names as its replacement, in its
+    #: warning, decorator, or docstring.
+    deprecated_for: str = ""
+    line: int = 0
+
+    @property
+    def name(self) -> str:
+        return self.qualname.rsplit(".", 1)[-1]
+
+    @property
+    def container(self) -> str:
+        """What holds it: the class for a method, the module otherwise."""
+        return self.qualname.rsplit(".", 1)[0] if "." in self.qualname else ""
+
+    def signature(self) -> str:
+        return f"{self.qualname}({', '.join(p.render() for p in self.params)})"
+
+
+@dataclass
+class Surface:
+    """Every public member of a library, keyed by the dotted path a caller uses."""
+
+    #: ``storekit.Client.fetch_all`` -> the member, however it got there.
+    public: dict[str, Member] = field(default_factory=dict)
+    #: Modules that could not be parsed, with the reason.
+    skipped: dict[str, str] = field(default_factory=dict)
+
+    def by_definition(self) -> dict[tuple[str, str], Member]:
+        """The same members keyed by where they are defined."""
+        return {(m.module, m.qualname): m for m in self.public.values()}
+
+
+def read(root: Path) -> Surface:
+    """Read the public API of every top-level package or module under ``root``.
+
+    ``root`` may also be a package directory itself; its parent is read then.
+    """
+    if (root / "__init__.py").exists():
+        root = root.parent
+    modules = _modules(root)
+    definitions: dict[str, dict[str, Member]] = {}
+    imports: dict[str, dict[str, tuple[str, str]]] = {}
+    exported: dict[str, set[str] | None] = {}
+    surface = Surface()
+
+    for dotted, path in modules.items():
+        try:
+            tree = ast.parse(read_source(path), filename=str(path))
+        except (SyntaxError, UnicodeDecodeError, OSError) as exc:
+            surface.skipped[dotted] = str(exc)
+            continue
+        definitions[dotted] = _definitions(dotted, tree)
+        imports[dotted] = _imports(dotted, tree, path.name == "__init__.py")
+        exported[dotted] = _all(tree)
+
+    for dotted in modules:
+        if dotted not in definitions or _private_module(dotted):
+            continue
+        allowed = exported[dotted]
+
+        def visible(name: str, allowed: set[str] | None = allowed) -> bool:
+            return name in allowed if allowed is not None else not name.startswith("_")
+
+        for name, member in definitions[dotted].items():
+            if "." not in name and visible(name):
+                _publish(surface, f"{dotted}.{name}", member, definitions[dotted])
+        for alias, (source, original) in imports[dotted].items():
+            member = definitions.get(source, {}).get(original)
+            if member is not None and visible(alias):
+                _publish(surface, f"{dotted}.{alias}", member, definitions[source])
+    return surface
+
+
+def _publish(surface: Surface, path: str, member: Member, siblings: dict[str, Member]) -> None:
+    surface.public.setdefault(path, member)
+    if member.kind == "class":
+        for qualname, method in siblings.items():
+            if qualname.startswith(f"{member.qualname}."):
+                surface.public.setdefault(f"{path}.{method.name}", method)
+
+
+def _modules(root: Path) -> dict[str, Path]:
+    """Dotted module name -> file, for every package or module at ``root``."""
+    found: dict[str, Path] = {}
+    for path in sorted(root.rglob("*.py")):
+        relative = path.relative_to(root)
+        parts = relative.parts
+        if any(p.endswith((".dist-info", ".egg-info", ".data")) for p in parts):
+            continue
+        if any(p in _SKIP_DIRS for p in parts[:-1]):
+            continue
+        # Only the importable tree: every directory above the file is a package.
+        if any(
+            not (root.joinpath(*parts[:i]) / "__init__.py").exists() for i in range(1, len(parts))
+        ):
+            continue
+        dotted = ".".join(parts[:-1] + ((path.stem,) if path.stem != "__init__" else ()))
+        if dotted:
+            found[dotted] = path
+    return found
+
+
+def _private_module(dotted: str) -> bool:
+    return any(part.startswith("_") for part in dotted.split("."))
+
+
+def _all(tree: ast.Module) -> set[str] | None:
+    """A module's literal ``__all__``, or None when it has none we can read."""
+    for node in tree.body:
+        names_all = isinstance(node, ast.Assign) and any(
+            isinstance(t, ast.Name) and t.id == "__all__" for t in node.targets
+        )
+        if (
+            names_all
+            and isinstance(node.value, (ast.List, ast.Tuple))
+            and all(
+                isinstance(e, ast.Constant) and isinstance(e.value, str) for e in node.value.elts
+            )
+        ):
+            return {e.value for e in node.value.elts}
+    return None
+
+
+def _imports(dotted: str, tree: ast.Module, is_package: bool) -> dict[str, tuple[str, str]]:
+    """``alias -> (source module, original name)`` for a module's top-level imports."""
+    package = dotted if is_package else dotted.rpartition(".")[0]
+    found: dict[str, tuple[str, str]] = {}
+    for node in tree.body:
+        if not isinstance(node, ast.ImportFrom):
+            continue
+        if node.level:
+            base = package.split(".")
+            base = base[: len(base) - (node.level - 1)] if node.level > 1 else base
+            source = ".".join(base + ([node.module] if node.module else []))
+        else:
+            source = node.module or ""
+        for alias in node.names:
+            if alias.name != "*":
+                found[alias.asname or alias.name] = (source, alias.name)
+    return found
+
+
+def _definitions(dotted: str, tree: ast.Module) -> dict[str, Member]:
+    members: dict[str, Member] = {}
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            members[node.name] = _function(dotted, node.name, node, "function", tree.body)
+        elif isinstance(node, ast.ClassDef):
+            methods = [
+                child
+                for child in node.body
+                if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef))
+                and (not child.name.startswith("_") or child.name == "__init__")
+            ]
+            init = next((m for m in methods if m.name == "__init__"), None)
+            members[node.name] = Member(
+                module=dotted,
+                qualname=node.name,
+                kind="class",
+                params=_params(init, drop_first=True) if init else (),
+                methods=frozenset(m.name for m in methods if m.name != "__init__"),
+                line=node.lineno,
+            )
+            for method in methods:
+                if method.name == "__init__":
+                    continue
+                qualname = f"{node.name}.{method.name}"
+                members[qualname] = _function(dotted, qualname, method, "method", node.body)
+    return members
+
+
+def _function(dotted: str, qualname: str, node, kind: str, scope: list[ast.stmt]) -> Member:
+    is_static = any(_decorator_name(d) == "staticmethod" for d in node.decorator_list)
+    deprecated, replacement = _deprecation(node, scope)
+    return Member(
+        module=dotted,
+        qualname=qualname,
+        kind=kind,
+        params=_params(node, drop_first=kind == "method" and not is_static),
+        deprecated=deprecated,
+        deprecated_for=replacement,
+        line=node.lineno,
+    )
+
+
+def _params(node, drop_first: bool) -> tuple[Param, ...]:
+    args = node.args
+    positional = [*args.posonlyargs, *args.args]
+    defaults_from = len(positional) - len(args.defaults)
+    params: list[Param] = []
+    for index, arg in enumerate(positional):
+        kind = "positional" if index < len(args.posonlyargs) else "normal"
+        params.append(Param(arg.arg, kind, index >= defaults_from))
+    if args.vararg:
+        params.append(Param(args.vararg.arg, "var_positional", False))
+    for arg, default in zip(args.kwonlyargs, args.kw_defaults, strict=True):
+        params.append(Param(arg.arg, "keyword", default is not None))
+    if args.kwarg:
+        params.append(Param(args.kwarg.arg, "var_keyword", False))
+    return tuple(params[1:] if drop_first and params and params[0].kind != "keyword" else params)
+
+
+def _decorator_name(node: ast.expr) -> str:
+    target = node.func if isinstance(node, ast.Call) else node
+    if isinstance(target, ast.Attribute):
+        return target.attr
+    return target.id if isinstance(target, ast.Name) else ""
+
+
+_DEPRECATION_CATEGORIES = {"DeprecationWarning", "PendingDeprecationWarning", "FutureWarning"}
+
+
+def _deprecation(node, scope: list[ast.stmt]) -> tuple[bool, str]:
+    """Whether a function is deprecated, and the sibling it names as replacement.
+
+    Deprecated means a ``@deprecated`` decorator, or a ``warnings.warn`` the body
+    always raises that is about deprecation: a deprecation category, or
+    "deprecat" in the message. A warning about something else -- an insecure
+    option -- is not, and nor is one raised only for a deprecated argument.
+
+    The replacement must be *named*: a sibling (a method of the same class, or
+    a function of the same module) mentioned in the warning, the decorator, or
+    the docstring. Calling a sibling is not naming it -- a deprecated function
+    usually calls helpers, often as its whole body.
+    """
+    texts: list[str] = []
+    deprecated = False
+    for decorator in node.decorator_list:
+        if "deprecat" in _decorator_name(decorator).lower():
+            deprecated = True
+            texts.extend(_strings(decorator))
+    # Only a warning the body always raises deprecates the function. One inside
+    # an `if` -- `if skip_defaults is not None: warn(...)` -- deprecates an
+    # argument, and the function itself is as current as ever.
+    warn_calls = [
+        stmt.value
+        for stmt in node.body
+        if isinstance(stmt, ast.Expr)
+        and isinstance(stmt.value, ast.Call)
+        and _decorator_name(stmt.value) == "warn"
+    ]
+    for call in warn_calls:
+        if _about_deprecation(call):
+            deprecated = True
+            texts.extend(_strings(call))
+    if not deprecated:
+        return False, ""
+    docstring = ast.get_docstring(node)
+    if docstring:
+        texts.append(docstring)
+
+    siblings = {
+        n.name
+        for n in scope
+        if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)) and n.name != node.name
+    }
+    named = {
+        name for name in siblings for text in texts if re.search(rf"\b{re.escape(name)}\b", text)
+    }
+    return True, named.pop() if len(named) == 1 else ""
+
+
+def _strings(node: ast.AST) -> list[str]:
+    return [
+        child.value
+        for child in ast.walk(node)
+        if isinstance(child, ast.Constant) and isinstance(child.value, str)
+    ]
+
+
+def _about_deprecation(call: ast.Call) -> bool:
+    for arg in [*call.args, *(k.value for k in call.keywords)]:
+        if _decorator_name(arg) in _DEPRECATION_CATEGORIES:
+            return True
+        if any("deprecat" in text.lower() for text in _strings(arg)):
+            return True
+    return False

patchahead/ci.py

@@ -0,0 +1,301 @@
+"""PatchAhead as a CI step: ``python -m patchahead.ci``.
+
+Built for the pull requests Dependabot and Renovate open. Such a pull request
+already says which packages moved between which versions, and usually quotes
+their release notes. This module reads both:
+
+1. **The release notes** in the pull request body (Dependabot writes them as
+   HTML; the Markdown parser reads that).
+2. **The library itself.** For each package the pull request bumps, the two
+   versions are compared with :mod:`patchahead.apidiff`. That finds renames the
+   notes never mention -- and it checks the notes: a rename to a name the new
+   version does not have is a misreading, and is dropped with a note.
+
+The changes are combined into one change document, migrated by the ordinary
+engine in a temporary copy, and reported the way GitHub Actions expects: step
+outputs in ``$GITHUB_OUTPUT``, a summary in ``$GITHUB_STEP_SUMMARY``, and the
+combined diff and pull-request summary as files. It never writes to the
+repository and never fails the step for a verdict -- ``action.yml`` decides
+that from the outputs, according to the workflow's ``fail-on``.
+
+Configuration comes from ``PATCHAHEAD_*`` environment variables, set by
+``action.yml`` from the action's inputs.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from patchahead import apidiff, engine, reporting
+from patchahead.config import ConfigError
+from patchahead.domain.change import BreakingChange, ChangeKind
+from patchahead.ingest import IngestError, parse_file
+from patchahead.ingest.base import ChangeDocument, parse_document
+from patchahead.ingest.structured import change_to_mapping
+from patchahead.workspace import RepositoryError, WorkspaceError
+
+log = logging.getLogger("patchahead.ci")
+
+#: Marks PatchAhead's pull-request comment, so a re-run updates it in place.
+COMMENT_MARKER = "<!-- patchahead -->"
+
+_VERSION = r"v?([0-9][\w.+!-]*?)\.?"
+_UPGRADE_PATTERNS = (
+    # Dependabot: "Bumps [storekit](https://...) from 4.9.0 to 5.0.0."
+    re.compile(rf"Bumps \[([^\]]+)\]\([^)]*\) from {_VERSION} to {_VERSION}(?=\s|$)"),
+    # Dependabot, grouped: "Updates `storekit` from 4.9.0 to 5.0.0"
+    re.compile(rf"Updates `([^`]+)` from {_VERSION} to {_VERSION}(?=\s|$)"),
+    # Dependabot title: "Bump storekit from 4.9.0 to 5.0.0"
+    re.compile(rf"\b[Bb]ump ([\w.\-\[\]]+) from {_VERSION} to {_VERSION}(?=\s|$)"),
+    # Renovate's table, whatever columns sit between the package and the change:
+    # "| [storekit](https://...) | major | `4.9.0` -> `5.0.0` |"
+    re.compile(rf"\|\s*\[([\w.\-]+)\]\([^)]*\)\s*\|[^\n]*?`{_VERSION}`\s*(?:->|→)\s*`{_VERSION}`"),
+)
+
+
+@dataclass(frozen=True)
+class Upgrade:
+    package: str
+    old: str
+    new: str
+
+    def __str__(self) -> str:
+        return f"{self.package} {self.old} -> {self.new}"
+
+
+@dataclass
+class Plan:
+    """What a CI run will migrate, and what it learned getting there."""
+
+    changes: list[BreakingChange] = field(default_factory=list)
+    upgrades: list[Upgrade] = field(default_factory=list)
+    sources: list[str] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+
+def upgrades_in(*texts: str) -> list[Upgrade]:
+    """The package upgrades a Dependabot or Renovate pull request describes."""
+    found: dict[str, Upgrade] = {}
+    for text in texts:
+        for pattern in _UPGRADE_PATTERNS:
+            for match in pattern.finditer(text or ""):
+                package, old, new = match.group(1), match.group(2), match.group(3)
+                found.setdefault(package.lower(), Upgrade(package, old, new))
+    return list(found.values())
+
+
+def plan(
+    *,
+    change_path: str = "",
+    pull_request: dict | None = None,
+    compare_versions: bool = True,
+    scratch: Path,
+) -> Plan:
+    """Collect the changes to migrate from every source the run was given."""
+    result = Plan()
+    noted: list[BreakingChange] = []
+
+    if change_path:
+        noted.extend(parse_file(change_path))
+        result.sources.append(f"the change document `{change_path}`")
+
+    if pull_request:
+        body = pull_request.get("body") or ""
+        title = pull_request.get("title") or ""
+        result.upgrades = upgrades_in(title, body)
+        if body.strip():
+            document = ChangeDocument(text=body, path="pull request body", suffix=".md")
+            read = [c for c in parse_document(document) if c.kind is not ChangeKind.UNKNOWN]
+            if read:
+                noted.extend(read)
+                result.sources.append("the release notes in this pull request")
+
+    surfaces: list[apidiff.Surface] = []
+    compared: list[BreakingChange] = []
+    if compare_versions:
+        for upgrade in result.upgrades:
+            try:
+                old = apidiff.read(apidiff.fetch(upgrade.package, upgrade.old, scratch / "old"))
+                new = apidiff.read(apidiff.fetch(upgrade.package, upgrade.new, scratch / "new"))
+            except apidiff.ApiDiffError as exc:
+                result.notes.append(f"could not compare {upgrade}: {exc}")
+                continue
+            surfaces.append(new)
+            diff = apidiff.compare(old, new, upgrade.package, (upgrade.old, upgrade.new))
+            compared.extend(diff.changes)
+            result.sources.append(f"a comparison of {upgrade}")
+
+    # A release note that renames something to a name the new version does not
+    # have was misread -- or describes a different package. Either way it is
+    # not something to rewrite code toward.
+    for change in noted:
+        missing = _absent_from(change, surfaces) if surfaces else ""
+        if missing:
+            result.notes.append(
+                f"dropped the reading `{change.target.symbol}` -> `{missing}` from the "
+                f"release notes: no `{missing}` exists in the new version's public API"
+            )
+            continue
+        result.changes.append(change)
+
+    known = {_identity(c) for c in result.changes}
+    for change in compared:
+        if _identity(change) not in known:
+            known.add(_identity(change))
+            result.changes.append(change)
+    return result
+
+
+def _identity(change: BreakingChange) -> tuple[str, str, str, str]:
+    """What makes two readings the same change. The owner is part of it: the same
+    keyword renamed on two functions is two changes."""
+    target = change.target
+    return change.kind.value, target.symbol, target.replacement, target.owner.lower()
+
+
+def _absent_from(change: BreakingChange, surfaces: list[apidiff.Surface]) -> str:
+    """The new name of a rename that none of the new versions define, else ""."""
+    new = change.target.replacement
+    if change.kind is ChangeKind.METHOD_RENAME:
+        names = {member.name for s in surfaces for member in s.public.values()}
+    elif change.kind is ChangeKind.KWARG_RENAME:
+        names = {p.name for s in surfaces for member in s.public.values() for p in member.params}
+    else:
+        # A field is data the API returns, not a name in the library's code.
+        return ""
+    return "" if new in names else new
+
+
+def run(environ: dict[str, str] | None = None) -> dict[str, str]:
+    """Do one CI run. Returns the step outputs it also writes to ``$GITHUB_OUTPUT``."""
+    env = dict(os.environ if environ is None else environ)
+    out_dir = Path(env.get("RUNNER_TEMP") or tempfile.gettempdir()) / "patchahead"
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    pull_request = None
+    if _flag(env, "PATCHAHEAD_FROM_PULL_REQUEST") and env.get("GITHUB_EVENT_PATH"):
+        event = json.loads(Path(env["GITHUB_EVENT_PATH"]).read_text(encoding="utf-8"))
+        pull_request = event.get("pull_request")
+        if pull_request is None:
+            log.warning("from-pull-request is set, but this run was not triggered by one")
+
+    outputs = {"outcome": "", "succeeded": "false", "complete": "true", "exit-code": "0"}
+    try:
+        with tempfile.TemporaryDirectory(prefix="patchahead-ci-") as scratch:
+            work = plan(
+                change_path=env.get("PATCHAHEAD_CHANGE", ""),
+                pull_request=pull_request,
+                compare_versions=_flag(env, "PATCHAHEAD_COMPARE_VERSIONS", default=True),
+                scratch=Path(scratch),
+            )
+        if not work.changes:
+            outputs["outcome"] = "nothing_to_migrate"
+            summary = _summary_header(outputs["outcome"], work, None)
+        else:
+            changes_path = out_dir / "changes.json"
+            changes_path.write_text(
+                json.dumps({"changes": [change_to_mapping(c) for c in work.changes]}, indent=2),
+                encoding="utf-8",
+            )
+            run_result = engine.migrate(
+                env.get("PATCHAHEAD_REPO") or ".",
+                changes_path,
+                engine.EngineOptions(
+                    write_artifacts=False, test_command=env.get("PATCHAHEAD_TEST_COMMAND", "")
+                ),
+            )
+            from patchahead.cli import _migration_exit_code
+
+            code = _migration_exit_code(
+                run_result,
+                require_complete=_flag(env, "PATCHAHEAD_REQUIRE_COMPLETE"),
+            )
+            outcome = run_result.outcome
+            outputs.update(
+                {
+                    "outcome": outcome.value if outcome else "nothing_to_migrate",
+                    "succeeded": str(run_result.succeeded).lower(),
+                    "complete": str(run_result.complete).lower(),
+                    "exit-code": str(code),
+                    "changes": str(changes_path),
+                }
+            )
+            if run_result.diff:
+                diff_path = out_dir / "patchahead.diff"
+                diff_path.write_text(run_result.diff, encoding="utf-8")
+                outputs["diff"] = str(diff_path)
+            summary = _summary_header(outputs["outcome"], work, run_result) + "\n\n".join(
+                reporting.render_pr_markdown(result) for result in run_result.results
+            )
+    except (IngestError, RepositoryError, ConfigError, WorkspaceError) as exc:
+        outputs.update({"outcome": "error", "exit-code": "2"})
+        summary = f"## PatchAhead could not run\n\n{exc}\n"
+        log.error("%s", exc)
+
+    summary_path = out_dir / "summary.md"
+    summary_path.write_text(f"{COMMENT_MARKER}\n{summary}", encoding="utf-8")
+    outputs["summary"] = str(summary_path)
+    _append(env.get("GITHUB_STEP_SUMMARY"), summary)
+    _append(env.get("GITHUB_OUTPUT"), "".join(f"{k}={v}\n" for k, v in outputs.items()))
+    return outputs
+
+
+_HEADLINES = {
+    "migrated": "verified migration",
+    "patched_unverified": "patched, not verified",
+    "validation_failed": "rejected by the tests",
+    "not_plannable": "found affected code it would not rewrite",
+    "patch_failed": "could not apply the patch",
+    "unsupported_change": "nothing it can migrate",
+    "no_impact": "no affected code",
+    "nothing_to_migrate": "nothing to migrate",
+}
+
+
+def _summary_header(outcome: str, work: Plan, run_result) -> str:
+    lines = [f"## PatchAhead: {_HEADLINES.get(outcome, outcome)}", ""]
+    if run_result is not None and run_result.diff:
+        lines.append(
+            "PatchAhead proposed a patch in a temporary copy of this branch; nothing was "
+            "committed. The diff and the evidence are below."
+        )
+    if work.sources:
+        lines.append(f"Read from {', '.join(work.sources)}.")
+    elif not work.changes:
+        lines.append(
+            "No change document was given, and this pull request names no breaking change "
+            "PatchAhead could read."
+        )
+    if run_result is not None and not run_result.complete:
+        lines.append("Code or tests still use an old name; see each change's last section.")
+    if work.notes:
+        lines += ["", "**Notes**", ""] + [f"- {note}" for note in work.notes]
+    return "\n".join(lines) + "\n\n"
+
+
+def _flag(env: dict[str, str], name: str, default: bool = False) -> bool:
+    value = env.get(name, "").strip().lower()
+    return default if not value else value in ("1", "true", "yes", "on")
+
+
+def _append(path: str | None, text: str) -> None:
+    if path:
+        with open(path, "a", encoding="utf-8") as handle:
+            handle.write(text)
+
+
+def main() -> int:
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+    outputs = run()
+    log.info("outcome: %s (exit code %s)", outputs["outcome"], outputs["exit-code"])
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())