dycw-actions 0.3.2__py3-none-any.whl → 0.7.1__py3-none-any.whl

actions/pre_commit/conformalize_repo/lib.py

@@ -0,0 +1,1293 @@
+from __future__ import annotations
+
+import sys
+from contextlib import contextmanager, suppress
+from itertools import product
+from pathlib import Path
+from re import MULTILINE, escape, search, sub
+from shlex import join
+from string import Template
+from subprocess import CalledProcessError
+from typing import TYPE_CHECKING, Literal, assert_never
+
+import tomlkit
+from ruamel.yaml.scalarstring import LiteralScalarString
+from tomlkit import TOMLDocument, table
+from tomlkit.exceptions import NonExistentKey
+from utilities.inflect import counted_noun
+from utilities.pathlib import get_repo_root
+from utilities.re import extract_groups
+from utilities.subprocess import ripgrep
+from utilities.text import repr_str, strip_and_dedent
+from utilities.version import ParseVersionError, Version, parse_version
+from utilities.whenever import HOUR, get_now
+from whenever import ZonedDateTime
+from xdg_base_dirs import xdg_cache_home
+
+from actions import __version__
+from actions.action_dicts.lib import (
+    run_action_pre_commit_dict,
+    run_action_publish_dict,
+    run_action_pyright_dict,
+    run_action_pytest_dict,
+    run_action_ruff_dict,
+    run_action_tag_dict,
+)
+from actions.constants import YAML_INSTANCE
+from actions.logging import LOGGER
+from actions.pre_commit.conformalize_repo.constants import (
+    ACTIONS_URL,
+    BUMPVERSION_TOML,
+    CONFORMALIZE_REPO_SUB_CMD,
+    COVERAGERC_TOML,
+    DOCKERFMT_URL,
+    ENVRC,
+    GITHUB_PULL_REQUEST_YAML,
+    GITHUB_PUSH_YAML,
+    GITIGNORE,
+    MAX_PYTHON_VERSION,
+    PATH_CONFIGS,
+    PRE_COMMIT_CONFIG_YAML,
+    PRE_COMMIT_HOOKS_URL,
+    PYPROJECT_TOML,
+    PYRIGHTCONFIG_JSON,
+    PYTEST_TOML,
+    README_MD,
+    RUFF_TOML,
+    RUFF_URL,
+    SHELLCHECK_URL,
+    SHFMT_URL,
+    TAPLO_URL,
+    UV_URL,
+)
+from actions.pre_commit.conformalize_repo.settings import SETTINGS
+from actions.pre_commit.format_requirements.constants import FORMAT_REQUIREMENTS_SUB_CMD
+from actions.pre_commit.replace_sequence_strs.constants import (
+    REPLACE_SEQUENCE_STRS_SUB_CMD,
+)
+from actions.pre_commit.touch_empty_py.constants import TOUCH_EMPTY_PY_SUB_CMD
+from actions.pre_commit.touch_py_typed.constants import TOUCH_PY_TYPED_SUB_CMD
+from actions.pre_commit.utilities import (
+    ensure_aot_contains,
+    ensure_contains,
+    ensure_contains_partial_dict,
+    ensure_contains_partial_str,
+    ensure_not_contains,
+    get_aot,
+    get_array,
+    get_dict,
+    get_list,
+    get_table,
+    yield_json_dict,
+    yield_text_file,
+    yield_toml_doc,
+    yield_yaml_dict,
+)
+from actions.utilities import logged_run, write_text
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, MutableSet
+
+    from tomlkit.items import Table
+    from utilities.types import PathLike
+
+    from actions.types import StrDict
+
+
+def conformalize_repo(
+    *,
+    coverage: bool = SETTINGS.coverage,
+    description: str | None = SETTINGS.description,
+    envrc: bool = SETTINGS.envrc,
+    envrc__uv: bool = SETTINGS.envrc__uv,
+    envrc__uv__native_tls: bool = SETTINGS.envrc__uv__native_tls,
+    github__pull_request__pre_commit: bool = SETTINGS.github__pull_request__pre_commit,
+    github__pull_request__pre_commit__gitea: bool = SETTINGS.github__pull_request__pre_commit__gitea,
+    github__pull_request__pyright: bool = SETTINGS.github__pull_request__pyright,
+    github__pull_request__pytest__macos: bool = SETTINGS.github__pull_request__pytest__macos,
+    github__pull_request__pytest__ubuntu: bool = SETTINGS.github__pull_request__pytest__ubuntu,
+    github__pull_request__pytest__windows: bool = SETTINGS.github__pull_request__pytest__windows,
+    github__pull_request__ruff: bool = SETTINGS.github__pull_request__ruff,
+    github__push__publish: bool = SETTINGS.github__push__publish,
+    github__push__tag: bool = SETTINGS.github__push__tag,
+    github__push__tag__major: bool = SETTINGS.github__push__tag__major,
+    github__push__tag__major_minor: bool = SETTINGS.github__push__tag__major_minor,
+    github__push__tag__latest: bool = SETTINGS.github__push__tag__latest,
+    gitignore: bool = SETTINGS.gitignore,
+    package_name: str | None = SETTINGS.package_name,
+    pre_commit__dockerfmt: bool = SETTINGS.pre_commit__dockerfmt,
+    pre_commit__prettier: bool = SETTINGS.pre_commit__prettier,
+    pre_commit__python: bool = SETTINGS.pre_commit__python,
+    pre_commit__ruff: bool = SETTINGS.pre_commit__ruff,
+    pre_commit__shell: bool = SETTINGS.pre_commit__shell,
+    pre_commit__taplo: bool = SETTINGS.pre_commit__taplo,
+    pre_commit__uv: bool = SETTINGS.pre_commit__uv,
+    pre_commit__uv__script: str | None = SETTINGS.pre_commit__uv__script,
+    pyproject: bool = SETTINGS.pyproject,
+    pyproject__project__optional_dependencies__scripts: bool = SETTINGS.pyproject__project__optional_dependencies__scripts,
+    pyproject__tool__uv__indexes: list[
+        tuple[str, str]
+    ] = SETTINGS.pyproject__tool__uv__indexes,
+    pyright: bool = SETTINGS.pyright,
+    pytest: bool = SETTINGS.pytest,
+    pytest__asyncio: bool = SETTINGS.pytest__asyncio,
+    pytest__ignore_warnings: bool = SETTINGS.pytest__ignore_warnings,
+    pytest__timeout: int | None = SETTINGS.pytest__timeout,
+    python_package_name: str | None = SETTINGS.python_package_name,
+    python_version: str = SETTINGS.python_version,
+    readme: bool = SETTINGS.readme,
+    repo_name: str | None = SETTINGS.repo_name,
+    ruff: bool = SETTINGS.ruff,
+    run_version_bump: bool = SETTINGS.run_version_bump,
+    script: str | None = SETTINGS.script,
+) -> None:
+    LOGGER.info(
+        strip_and_dedent("""
+            Running '%s' (version %s) with settings:
+             - coverage                                           = %s
+             - description                                        = %s
+             - envrc                                              = %s
+             - envrc__uv                                          = %s
+             - envrc__uv__native_tls                              = %s
+             - github__pull_request__pre_commit                   = %s
+             - github__pull_request__pre_commit__gitea            = %s
+             - github__pull_request__pyright                      = %s
+             - github__pull_request__pytest__macos                = %s
+             - github__pull_request__pytest__ubuntu               = %s
+             - github__pull_request__pytest__windows              = %s
+             - github__pull_request__ruff                         = %s
+             - github__push__publish                              = %s
+             - github__push__tag                                  = %s
+             - github__push__tag__major                           = %s
+             - github__push__tag__major_minor                     = %s
+             - github__push__tag__latest                          = %s
+             - gitignore                                          = %s
+             - package_name                                       = %s
+             - pre_commit__dockerfmt                              = %s
+             - pre_commit__prettier                               = %s
+             - pre_commit__python                                 = %s
+             - pre_commit__ruff                                   = %s
+             - pre_commit__shell                                  = %s
+             - pre_commit__taplo                                  = %s
+             - pre_commit__uv                                     = %s
+             - pre_commit__uv__script                             = %s
+             - pyproject                                          = %s
+             - pyproject__project__optional_dependencies__scripts = %s
+             - pyproject__tool__uv__indexes                       = %s
+             - pyright                                            = %s
+             - pytest                                             = %s
+             - pytest__asyncio                                    = %s
+             - pytest__ignore_warnings                            = %s
+             - pytest__timeout                                    = %s
+             - python_package_name                                = %s
+             - python_version                                     = %s
+             - readme                                             = %s
+             - repo_name                                          = %s
+             - ruff                                               = %s
+             - run_version_bump                                   = %s
+             - script                                             = %s
+        """),
+        conformalize_repo.__name__,
+        __version__,
+        coverage,
+        description,
+        envrc,
+        envrc__uv,
+        envrc__uv__native_tls,
+        github__pull_request__pre_commit,
+        github__pull_request__pre_commit__gitea,
+        github__pull_request__pyright,
+        github__pull_request__pytest__macos,
+        github__pull_request__pytest__ubuntu,
+        github__pull_request__pytest__windows,
+        github__pull_request__ruff,
+        github__push__publish,
+        github__push__tag,
+        github__push__tag__major,
+        github__push__tag__major_minor,
+        github__push__tag__latest,
+        gitignore,
+        package_name,
+        pre_commit__dockerfmt,
+        pre_commit__prettier,
+        pre_commit__python,
+        pre_commit__ruff,
+        pre_commit__shell,
+        pre_commit__taplo,
+        pre_commit__uv,
+        pre_commit__uv__script,
+        pyproject,
+        pyproject__project__optional_dependencies__scripts,
+        pyproject__tool__uv__indexes,
+        pyright,
+        pytest,
+        pytest__asyncio,
+        pytest__ignore_warnings,
+        pytest__timeout,
+        python_package_name,
+        python_version,
+        readme,
+        repo_name,
+        ruff,
+        run_version_bump,
+        script,
+    )
+    modifications: set[Path] = set()
+    add_bumpversion_toml(
+        modifications=modifications,
+        pyproject=pyproject,
+        package_name=package_name,
+        python_package_name=python_package_name,
+    )
+    check_versions()
+    run_pre_commit_update(modifications=modifications)
+    run_ripgrep_and_replace(modifications=modifications, version=python_version)
+    update_action_file_extensions(modifications=modifications)
+    update_action_versions(modifications=modifications)
+    add_pre_commit_config_yaml(
+        modifications=modifications,
+        dockerfmt=pre_commit__dockerfmt,
+        prettier=pre_commit__prettier,
+        python=pre_commit__python,
+        ruff=pre_commit__ruff,
+        shell=pre_commit__shell,
+        taplo=pre_commit__taplo,
+        uv=pre_commit__uv,
+        script=script,
+    )
+    if coverage:
+        add_coveragerc_toml(modifications=modifications)
+    if envrc or envrc__uv or envrc__uv__native_tls:
+        add_envrc(
+            modifications=modifications,
+            uv=envrc__uv,
+            uv__native_tls=envrc__uv__native_tls,
+            python_version=python_version,
+            script=script,
+        )
+    if (
+        github__pull_request__pre_commit
+        or github__pull_request__pre_commit__gitea
+        or github__pull_request__pyright
+        or github__pull_request__pytest__windows
+        or github__pull_request__pytest__macos
+        or github__pull_request__pytest__ubuntu
+        or github__pull_request__ruff
+    ):
+        add_github_pull_request_yaml(
+            modifications=modifications,
+            pre_commit=github__pull_request__pre_commit,
+            pre_commit__gitea=github__pull_request__pre_commit__gitea,
+            pyright=github__pull_request__pyright,
+            pytest__windows=github__pull_request__pytest__windows,
+            pytest__macos=github__pull_request__pytest__macos,
+            pytest__ubuntu=github__pull_request__pytest__ubuntu,
+            pytest__timeout=pytest__timeout,
+            python_version=python_version,
+            ruff=ruff,
+            script=script,
+        )
+    if (
+        github__push__publish
+        or github__push__tag
+        or github__push__tag__major_minor
+        or github__push__tag__major
+        or github__push__tag__latest
+    ):
+        add_github_push_yaml(
+            modifications=modifications,
+            publish=github__push__publish,
+            tag=github__push__tag,
+            tag__major_minor=github__push__tag__major_minor,
+            tag__major=github__push__tag__major,
+            tag__latest=github__push__tag__latest,
+        )
+    if gitignore:
+        add_gitignore(modifications=modifications)
+    if (
+        pyproject
+        or pyproject__project__optional_dependencies__scripts
+        or (len(pyproject__tool__uv__indexes) >= 1)
+    ):
+        add_pyproject_toml(
+            modifications=modifications,
+            python_version=python_version,
+            description=description,
+            package_name=package_name,
+            readme=readme,
+            optional_dependencies__scripts=pyproject__project__optional_dependencies__scripts,
+            python_package_name=python_package_name,
+            tool__uv__indexes=pyproject__tool__uv__indexes,
+        )
+    if pyright:
+        add_pyrightconfig_json(
+            modifications=modifications, python_version=python_version, script=script
+        )
+    if (
+        pytest
+        or pytest__asyncio
+        or pytest__ignore_warnings
+        or (pytest__timeout is not None)
+    ):
+        add_pytest_toml(
+            modifications=modifications,
+            asyncio=pytest__asyncio,
+            ignore_warnings=pytest__ignore_warnings,
+            timeout=pytest__timeout,
+            coverage=coverage,
+            package_name=package_name,
+            python_package_name=python_package_name,
+            script=script,
+        )
+    if readme:
+        add_readme_md(
+            modifications=modifications, name=repo_name, description=description
+        )
+    if ruff:
+        add_ruff_toml(modifications=modifications, python_version=python_version)
+    if run_version_bump:
+        run_bump_my_version(modifications=modifications)
+    if len(modifications) >= 1:
+        LOGGER.info(
+            "Exiting due to %s: %s",
+            counted_noun(modifications, "modification"),
+            ", ".join(map(repr_str, sorted(modifications))),
+        )
+        sys.exit(1)
+
+
+##
+
+
+def add_bumpversion_toml(
+    *,
+    modifications: MutableSet[Path] | None = None,
+    pyproject: bool = SETTINGS.pyproject,
+    package_name: str | None = SETTINGS.package_name,
+    python_package_name: str | None = SETTINGS.python_package_name,
+) -> None:
+    with yield_bumpversion_toml(modifications=modifications) as doc:
+        tool = get_table(doc, "tool")
+        bumpversion = get_table(tool, "bumpversion")
+        if pyproject:
+            files = get_aot(bumpversion, "files")
+            ensure_aot_contains(
+                files,
+                _add_bumpversion_toml_file(PYPROJECT_TOML, 'version = "${version}"'),
+            )
+    if (
+        python_package_name_use := get_python_package_name(
+            package_name=package_name, python_package_name=python_package_name
+        )
+    ) is not None:
+        files = get_aot(bumpversion, "files")
+        ensure_aot_contains(
+            files,
+            _add_bumpversion_toml_file(
+                f"src/{python_package_name_use}/__init__.py",
+                '__version__ = "${version}"',
+            ),
+        )
+
+
+def _add_bumpversion_toml_file(path: PathLike, template: str, /) -> Table:
+    tab = table()
+    tab["filename"] = str(path)
+    tab["search"] = Template(template).substitute(version="{current_version}")
+    tab["replace"] = Template(template).substitute(version="{new_version}")
+    return tab
+
+
+##
+
+
+def add_coveragerc_toml(*, modifications: MutableSet[Path] | None = None) -> None:
+    with yield_toml_doc(COVERAGERC_TOML, modifications=modifications) as doc:
+        html = get_table(doc, "html")
+        html["directory"] = ".coverage/html"
+        report = get_table(doc, "report")
+        exclude_also = get_array(report, "exclude_also")
+        ensure_contains(exclude_also, "@overload", "if TYPE_CHECKING:")
+        report["fail_under"] = 100.0
+        report["skip_covered"] = True
+        report["skip_empty"] = True
+        run = get_table(doc, "run")
+        run["branch"] = True
+        run["data_file"] = ".coverage/data"
+        run["parallel"] = True
+
+
+##
+
+
+def add_envrc(
+    *,
+    modifications: MutableSet[Path] | None = None,
+    uv: bool = SETTINGS.envrc__uv,
+    uv__native_tls: bool = SETTINGS.envrc__uv__native_tls,
+    python_version: str = SETTINGS.python_version,
+    script: str | None = SETTINGS.script,
+) -> None:
+    with yield_text_file(ENVRC, modifications=modifications) as context:
+        shebang = strip_and_dedent("""
+            #!/usr/bin/env sh
+            # shellcheck source=/dev/null
+        """)
+        if search(escape(shebang), context.output, flags=MULTILINE) is None:
+            context.output += f"\n\n{shebang}"
+
+        echo = strip_and_dedent("""
+            # echo
+            echo_date() { echo "[$(date +'%Y-%m-%d %H:%M:%S')] $*" >&2; }
+        """)
+        if search(escape(echo), context.output, flags=MULTILINE) is None:
+            context.output += f"\n\n{echo}"
+
+        if uv:
+            uv_text = _add_envrc_uv_text(
+                native_tls=uv__native_tls, python_version=python_version, script=script
+            )
+            if search(escape(uv_text), context.output, flags=MULTILINE) is None:
+                context.output += f"\n\n{echo}"
+
+
+def _add_envrc_uv_text(
+    *,
+    native_tls: bool = SETTINGS.envrc__uv__native_tls,
+    python_version: str = SETTINGS.python_version,
+    script: str | None = SETTINGS.script,
+) -> str:
+    lines: list[str] = [
+        strip_and_dedent("""
+            # uv
+            export UV_MANAGED_PYTHON='true'
+        """)
+    ]
+    if native_tls:
+        lines.append("export UV_NATIVE_TLS='true'")
+    lines.append(
+        strip_and_dedent(f"""
+            export UV_PRERELEASE='disallow'
+            export UV_PYTHON='{python_version}'
+            if ! command -v uv >/dev/null 2>&1; then
+                echo_date "ERROR: 'uv' not found" && exit 1
+            fi
+            activate='.venv/bin/activate'
+            if [ -f $activate ]; then
+                . $activate
+            else
+                uv venv
+            fi
+        """)
+    )
+    args: list[str] = ["uv", "sync"]
+    if script is None:
+        args.extend(["--all-extras", "--all-groups"])
+    args.extend(["--active", "--locked"])
+    if script is not None:
+        args.extend(["--script", script])
+    lines.append(join(args))
+    return "\n".join(lines)
+
+
+##
+
+
+def add_github_pull_request_yaml(
+    *,
+    modifications: MutableSet[Path] | None = None,
+    pre_commit: bool = SETTINGS.github__pull_request__pre_commit,
+    pre_commit__gitea: bool = SETTINGS.github__pull_request__pre_commit__gitea,
+    pyright: bool = SETTINGS.github__pull_request__pyright,
+    pytest__macos: bool = SETTINGS.github__pull_request__pytest__macos,
+    pytest__ubuntu: bool = SETTINGS.github__pull_request__pytest__ubuntu,
+    pytest__windows: bool = SETTINGS.github__pull_request__pytest__windows,
+    pytest__timeout: int | None = SETTINGS.pytest__timeout,
+    python_version: str = SETTINGS.python_version,
+    ruff: bool = SETTINGS.github__pull_request__ruff,
+    script: str | None = SETTINGS.script,
+) -> None:
+    with yield_yaml_dict(
+        GITHUB_PULL_REQUEST_YAML, modifications=modifications
+    ) as dict_:
+        dict_["name"] = "pull-request"
+        on = get_dict(dict_, "on")
+        pull_request = get_dict(on, "pull_request")
+        branches = get_list(pull_request, "branches")
+        ensure_contains(branches, "master")
+        schedule = get_list(on, "schedule")
+        ensure_contains(schedule, {"cron": "0 0 * * *"})
+        jobs = get_dict(dict_, "jobs")
+        if pre_commit:
+            pre_commit_dict = get_dict(jobs, "pre-commit")
+            pre_commit_dict["runs-on"] = "ubuntu-latest"
+            steps = get_list(pre_commit_dict, "steps")
+            ensure_contains(
+                steps,
+                run_action_pre_commit_dict(
+                    repos=LiteralScalarString(
+                        strip_and_dedent("""
+                            dycw/actions
+                            pre-commit/pre-commit-hooks
+                        """)
+                    ),
+                    gitea=pre_commit__gitea,
+                ),
+            )
+        if pyright:
+            pyright_dict = get_dict(jobs, "pyright")
+            pyright_dict["runs-on"] = "ubuntu-latest"
+            steps = get_list(pyright_dict, "steps")
+            ensure_contains(
+                steps,
+                run_action_pyright_dict(
+                    python_version=python_version, with_requirements=script
+                ),
+            )
+        if pytest__macos or pytest__ubuntu or pytest__windows:
+            pytest_dict = get_dict(jobs, "pytest")
+            env = get_dict(pytest_dict, "env")
+            env["CI"] = "1"
+            pytest_dict["name"] = (
+                "pytest (${{matrix.os}}, ${{matrix.python-version}}, ${{matrix.resolution}})"
+            )
+            pytest_dict["runs-on"] = "${{matrix.os}}"
+            steps = get_list(pytest_dict, "steps")
+            ensure_contains(
+                steps,
+                run_action_pytest_dict(
+                    python_version="${{matrix.python-version}}",
+                    resolution="${{matrix.resolution}}",
+                    with_requirements=script,
+                ),
+            )
+            strategy_dict = get_dict(pytest_dict, "strategy")
+            strategy_dict["fail-fast"] = False
+            matrix = get_dict(strategy_dict, "matrix")
+            os = get_list(matrix, "os")
+            if pytest__macos:
+                ensure_contains(os, "macos-latest")
+            if pytest__ubuntu:
+                ensure_contains(os, "ubuntu-latest")
+            if pytest__windows:
+                ensure_contains(os, "windows-latest")
+            python_version_dict = get_list(matrix, "python-version")
+            ensure_contains(python_version_dict, *yield_python_versions(python_version))
+            resolution = get_list(matrix, "resolution")
+            ensure_contains(resolution, "highest", "lowest-direct")
+            if pytest__timeout is not None:
+                pytest_dict["timeout-minutes"] = max(round(pytest__timeout / 60), 1)
+        if ruff:
+            ruff_dict = get_dict(jobs, "ruff")
+            ruff_dict["runs-on"] = "ubuntu-latest"
+            steps = get_list(ruff_dict, "steps")
+            ensure_contains(steps, run_action_ruff_dict())
+
+
+##
+
+
+def add_github_push_yaml(
+    *,
+    modifications: MutableSet[Path] | None = None,
+    publish: bool = SETTINGS.github__push__publish,
+    tag: bool = SETTINGS.github__push__tag,
+    tag__major_minor: bool = SETTINGS.github__push__tag__major_minor,
+    tag__major: bool = SETTINGS.github__push__tag__major,
+    tag__latest: bool = SETTINGS.github__push__tag__latest,
+) -> None:
+    with yield_yaml_dict(GITHUB_PUSH_YAML, modifications=modifications) as dict_:
+        dict_["name"] = "push"
+        on = get_dict(dict_, "on")
+        push = get_dict(on, "push")
+        branches = get_list(push, "branches")
+        ensure_contains(branches, "master")
+        jobs = get_dict(dict_, "jobs")
+        if publish:
+            publish_dict = get_dict(jobs, "publish")
+            environment = get_dict(publish_dict, "environment")
+            environment["name"] = "pypi"
+            permissions = get_dict(publish_dict, "permissions")
+            permissions["id-token"] = "write"
+            publish_dict["runs-on"] = "ubuntu-latest"
+            steps = get_list(publish_dict, "steps")
+            ensure_contains(steps, run_action_publish_dict())
+        if tag or tag__major_minor or tag__major or tag__latest:
+            tag_dict = get_dict(jobs, "tag")
+            tag_dict["runs-on"] = "ubuntu-latest"
+            steps = get_list(tag_dict, "steps")
+            ensure_contains(
+                steps,
+                run_action_tag_dict(
+                    major_minor=tag__major_minor, major=tag__major, latest=tag__latest
+                ),
+            )
+
+
+##
+
+
+def add_gitignore(*, modifications: MutableSet[Path] | None = None) -> None:
+    with yield_text_file(GITIGNORE, modifications=modifications) as context:
+        text = (PATH_CONFIGS / "gitignore").read_text()
+        if search(escape(text), context.output, flags=MULTILINE) is None:
+            context.output += f"\n\n{text}"
+
+
+##
+
+
+def add_pre_commit_config_yaml(
+    *,
+    modifications: MutableSet[Path] | None = None,
+    dockerfmt: bool = SETTINGS.pre_commit__dockerfmt,
+    prettier: bool = SETTINGS.pre_commit__prettier,
+    python: bool = SETTINGS.pre_commit__python,
+    ruff: bool = SETTINGS.pre_commit__ruff,
+    shell: bool = SETTINGS.pre_commit__shell,
+    taplo: bool = SETTINGS.pre_commit__taplo,
+    uv: bool = SETTINGS.pre_commit__uv,
+    script: str | None = SETTINGS.script,
+) -> None:
+    with yield_yaml_dict(PRE_COMMIT_CONFIG_YAML, modifications=modifications) as dict_:
+        _add_pre_commit_config_repo(dict_, ACTIONS_URL, CONFORMALIZE_REPO_SUB_CMD)
+        _add_pre_commit_config_repo(
+            dict_, PRE_COMMIT_HOOKS_URL, "check-executables-have-shebangs"
+        )
+        _add_pre_commit_config_repo(dict_, PRE_COMMIT_HOOKS_URL, "check-merge-conflict")
+        _add_pre_commit_config_repo(dict_, PRE_COMMIT_HOOKS_URL, "check-symlinks")
+        _add_pre_commit_config_repo(dict_, PRE_COMMIT_HOOKS_URL, "destroyed-symlinks")
+        _add_pre_commit_config_repo(dict_, PRE_COMMIT_HOOKS_URL, "detect-private-key")
+        _add_pre_commit_config_repo(dict_, PRE_COMMIT_HOOKS_URL, "end-of-file-fixer")
+        _add_pre_commit_config_repo(
+            dict_, PRE_COMMIT_HOOKS_URL, "mixed-line-ending", args=("add", ["--fix=lf"])
+        )
+        _add_pre_commit_config_repo(dict_, PRE_COMMIT_HOOKS_URL, "no-commit-to-branch")
+        _add_pre_commit_config_repo(
+            dict_,
+            PRE_COMMIT_HOOKS_URL,
+            "pretty-format-json",
+            args=("add", ["--autofix"]),
+        )
+        _add_pre_commit_config_repo(dict_, PRE_COMMIT_HOOKS_URL, "no-commit-to-branch")
+        _add_pre_commit_config_repo(dict_, PRE_COMMIT_HOOKS_URL, "trailing-whitespace")
+        if dockerfmt:
+            _add_pre_commit_config_repo(
+                dict_,
+                DOCKERFMT_URL,
+                "dockerfmt",
+                args=("add", ["--newline", "--write"]),
+            )
+        if prettier:
+            _add_pre_commit_config_repo(
+                dict_,
+                "local",
+                "prettier",
+                name="prettier",
+                entry="npx prettier --write",
+                language="system",
+                types_or=["markdown", "yaml"],
+            )
+        if python:
+            _add_pre_commit_config_repo(dict_, ACTIONS_URL, FORMAT_REQUIREMENTS_SUB_CMD)
+            _add_pre_commit_config_repo(
+                dict_, ACTIONS_URL, REPLACE_SEQUENCE_STRS_SUB_CMD
+            )
+            _add_pre_commit_config_repo(dict_, ACTIONS_URL, TOUCH_EMPTY_PY_SUB_CMD)
+            _add_pre_commit_config_repo(dict_, ACTIONS_URL, TOUCH_PY_TYPED_SUB_CMD)
+        if ruff:
+            _add_pre_commit_config_repo(
+                dict_, RUFF_URL, "ruff-check", args=("add", ["--fix"])
+            )
+            _add_pre_commit_config_repo(dict_, RUFF_URL, "ruff-format")
+        if shell:
+            _add_pre_commit_config_repo(dict_, SHFMT_URL, "shfmt")
+            _add_pre_commit_config_repo(dict_, SHELLCHECK_URL, "shellcheck")
+        if taplo:
+            _add_pre_commit_config_repo(
+                dict_,
+                TAPLO_URL,
+                "taplo-format",
+                args=(
+                    "exact",
+                    [
+                        "--option",
+                        "indent_tables=true",
+                        "--option",
+                        "indent_entries=true",
+                        "--option",
+                        "reorder_keys=true",
+                    ],
+                ),
+            )
+        if uv:
+            _add_pre_commit_config_repo(
+                dict_,
+                UV_URL,
+                "uv-lock",
+                files=None if script is None else rf"^{escape(script)}$",
+                args=(
+                    "add",
+                    ["--upgrade", "--resolution", "highest", "--prerelease", "disallow"]
+                    + ([] if script is None else [f"--script={script}"]),
+                ),
+            )
+
+
+def _add_pre_commit_config_repo(
+    pre_commit_dict: StrDict,
+    url: str,
+    id_: str,
+    /,
+    *,
+    name: str | None = None,
+    entry: str | None = None,
+    language: str | None = None,
+    files: str | None = None,
+    types_or: list[str] | None = None,
+    args: tuple[Literal["add", "exact"], list[str]] | None = None,
+) -> None:
+    repos_list = get_list(pre_commit_dict, "repos")
+    repo_dict = ensure_contains_partial_dict(
+        repos_list, {"repo": url}, extra={} if url == "local" else {"rev": "master"}
+    )
+    hooks_list = get_list(repo_dict, "hooks")
+    hook_dict = ensure_contains_partial_dict(hooks_list, {"id": id_})
+    if name is not None:
+        hook_dict["name"] = name
+    if entry is not None:
+        hook_dict["entry"] = entry
+    if language is not None:
+        hook_dict["language"] = language
+    if files is not None:
+        hook_dict["files"] = files
+    if types_or is not None:
+        hook_dict["types_or"] = types_or
+    if args is not None:
+        match args:
+            case "add", list() as args_i:
+                hook_args = get_list(hook_dict, "args")
+                ensure_contains(hook_args, *args_i)
+            case "exact", list() as args_i:
+                hook_dict["args"] = args_i
+            case never:
+                assert_never(never)
+
+
+##
+
+
+def add_pyproject_toml(
+    *,
+    modifications: MutableSet[Path] | None = None,
+    python_version: str = SETTINGS.python_version,
+    description: str | None = SETTINGS.description,
+    package_name: str | None = SETTINGS.package_name,
+    readme: bool = SETTINGS.readme,
+    optional_dependencies__scripts: bool = SETTINGS.pyproject__project__optional_dependencies__scripts,
+    python_package_name: str | None = SETTINGS.python_package_name,
+    tool__uv__indexes: list[tuple[str, str]] = SETTINGS.pyproject__tool__uv__indexes,
+) -> None:
+    with yield_toml_doc(PYPROJECT_TOML, modifications=modifications) as doc:
+        build_system = get_table(doc, "build-system")
+        build_system["build-backend"] = "uv_build"
+        build_system["requires"] = ["uv_build"]
+        project = get_table(doc, "project")
+        project["requires-python"] = f">= {python_version}"
+        if description is not None:
+            project["description"] = description
+        if package_name is not None:
+            project["name"] = package_name
+        if readme:
+            project["readme"] = "README.md"
+        project.setdefault("version", "0.1.0")
+        dependency_groups = get_table(doc, "dependency-groups")
+        dev = get_array(dependency_groups, "dev")
+        _ = ensure_contains_partial_str(dev, "dycw-utilities[test]")
+        _ = ensure_contains_partial_str(dev, "pyright")
+        _ = ensure_contains_partial_str(dev, "rich")
+        if optional_dependencies__scripts:
+            optional_dependencies = get_table(project, "optional-dependencies")
+            scripts = get_array(optional_dependencies, "scripts")
+            _ = ensure_contains_partial_str(scripts, "click")
+        if python_package_name is not None:
+            tool = get_table(doc, "tool")
+            uv = get_table(tool, "uv")
+            build_backend = get_table(uv, "build-backend")
+            build_backend["module-name"] = get_python_package_name(
+                package_name=package_name, python_package_name=python_package_name
+            )
+            build_backend["module-root"] = "src"
+        if len(tool__uv__indexes) >= 1:
+            tool = get_table(doc, "tool")
+            uv = get_table(tool, "uv")
+            indexes = get_aot(uv, "index")
+            for name, url in tool__uv__indexes:
+                index = table()
+                index["explicit"] = True
+                index["name"] = name
+                index["url"] = url
+                ensure_aot_contains(indexes, index)
+
+
+##
+
+
+def add_pyrightconfig_json(
+    *,
+    modifications: MutableSet[Path] | None = None,
+    python_version: str = SETTINGS.python_version,
+    script: str | None = SETTINGS.script,
+) -> None:
+    with yield_json_dict(PYRIGHTCONFIG_JSON, modifications=modifications) as dict_:
+        dict_["deprecateTypingAliases"] = True
+        dict_["enableReachabilityAnalysis"] = False
+        include = get_list(dict_, "include")
+        ensure_contains(include, "src" if script is None else script)
+        dict_["pythonVersion"] = python_version
+        dict_["reportCallInDefaultInitializer"] = True
+        dict_["reportImplicitOverride"] = True
+        dict_["reportImplicitStringConcatenation"] = True
+        dict_["reportImportCycles"] = True
+        dict_["reportMissingSuperCall"] = True
+        dict_["reportMissingTypeArgument"] = False
+        dict_["reportMissingTypeStubs"] = False
+        dict_["reportPrivateImportUsage"] = False
+        dict_["reportPrivateUsage"] = False
+        dict_["reportPropertyTypeMismatch"] = True
+        dict_["reportUninitializedInstanceVariable"] = True
+        dict_["reportUnknownArgumentType"] = False
+        dict_["reportUnknownMemberType"] = False
+        dict_["reportUnknownParameterType"] = False
+        dict_["reportUnknownVariableType"] = False
+        dict_["reportUnnecessaryComparison"] = False
+        dict_["reportUnnecessaryTypeIgnoreComment"] = True
+        dict_["reportUnusedCallResult"] = True
+        dict_["reportUnusedImport"] = False
+        dict_["reportUnusedVariable"] = False
+        dict_["typeCheckingMode"] = "strict"
+
+
+##
+
+
+def add_pytest_toml(
+    *,
+    modifications: MutableSet[Path] | None = None,
+    asyncio: bool = SETTINGS.pytest__asyncio,
+    ignore_warnings: bool = SETTINGS.pytest__ignore_warnings,
+    timeout: int | None = SETTINGS.pytest__timeout,
+    coverage: bool = SETTINGS.coverage,
+    package_name: str | None = SETTINGS.package_name,
+    python_package_name: str | None = SETTINGS.python_package_name,
+    script: str | None = SETTINGS.script,
+) -> None:
+    with yield_toml_doc(PYTEST_TOML, modifications=modifications) as doc:
+        pytest = get_table(doc, "pytest")
+        addopts = get_array(pytest, "addopts")
+        ensure_contains(
+            addopts,
+            "-ra",
+            "-vv",
+            "--color=auto",
+            "--durations=10",
+            "--durations-min=10",
+        )
+        if coverage and (
+            (
+                python_package_name_use := get_python_package_name(
+                    package_name=package_name, python_package_name=python_package_name
+                )
+            )
+            is not None
+        ):
+            ensure_contains(
+                addopts,
+                f"--cov={python_package_name_use}",
+                f"--cov-config={COVERAGERC_TOML}",
+                "--cov-report=html",
+            )
+        pytest["collect_imported_tests"] = False
+        pytest["empty_parameter_set_mark"] = "fail_at_collect"
+        filterwarnings = get_array(pytest, "filterwarnings")
+        ensure_contains(filterwarnings, "error")
+        pytest["minversion"] = "9.0"
+        pytest["strict"] = True
+        testpaths = get_array(pytest, "testpaths")
+        ensure_contains(testpaths, "src/tests" if script is None else "tests")
+        pytest["xfail_strict"] = True
+        if asyncio:
+            pytest["asyncio_default_fixture_loop_scope"] = "function"
+            pytest["asyncio_mode"] = "auto"
+        if ignore_warnings:
+            filterwarnings = get_array(pytest, "filterwarnings")
+            ensure_contains(
+                filterwarnings,
+                "ignore::DeprecationWarning",
+                "ignore::ResourceWarning",
+                "ignore::RuntimeWarning",
+            )
+        if timeout is not None:
+            pytest["timeout"] = str(timeout)
+
+
+##
+
+
+def add_readme_md(
+    *,
+    modifications: MutableSet[Path] | None = None,
+    name: str | None = SETTINGS.package_name,
+    description: str | None = SETTINGS.description,
+) -> None:
+    with yield_text_file(README_MD, modifications=modifications) as context:
+        lines: list[str] = []
+        if name is not None:
+            lines.append(f"# `{name}`")
+        if description is not None:
+            lines.append(description)
+        text = "\n\n".join(lines)
+        if search(escape(text), context.output, flags=MULTILINE) is None:
+            context.output += f"\n\n{text}"
+
+
+##
+
+
+def add_ruff_toml(
+    *,
+    modifications: MutableSet[Path] | None = None,
+    python_version: str = SETTINGS.python_version,
+) -> None:
+    with yield_toml_doc(RUFF_TOML, modifications=modifications) as doc:
+        doc["target-version"] = f"py{python_version.replace('.', '')}"
+        doc["unsafe-fixes"] = True
+        fmt = get_table(doc, "format")
+        fmt["preview"] = True
+        fmt["skip-magic-trailing-comma"] = True
+        lint = get_table(doc, "lint")
+        lint["explicit-preview-rules"] = True
+        fixable = get_array(lint, "fixable")
+        ensure_contains(fixable, "ALL")
+        ignore = get_array(lint, "ignore")
+        ensure_contains(
+            ignore,
+            "ANN401",  # any-type
+            "ASYNC109",  # async-function-with-timeout
+            "C901",  # complex-structure
+            "CPY",  # flake8-copyright
+            "D",  # pydocstyle
+            "E501",  # line-too-long
+            "PD",  # pandas-vet
+            "PERF203",  # try-except-in-loop
+            "PLC0415",  # import-outside-top-level
+            "PLE1205",  # logging-too-many-args
+            "PLR0904",  # too-many-public-methods
+            "PLR0911",  # too-many-return-statements
+            "PLR0912",  # too-many-branches
+            "PLR0913",  # too-many-arguments
+            "PLR0915",  # too-many-statements
+            "PLR2004",  # magic-value-comparison
+            "PT012",  # pytest-raises-with-multiple-statements
+            "PT013",  # pytest-incorrect-pytest-import
+            "PYI041",  # redundant-numeric-union
+            "S202",  # tarfile-unsafe-members
+            "S310",  # suspicious-url-open-usage
+            "S311",  # suspicious-non-cryptographic-random-usage
+            "S602",  # subprocess-popen-with-shell-equals-true
+            "S603",  # subprocess-without-shell-equals-true
+            "S607",  # start-process-with-partial-path
+            # preview
+            "S101",  # assert
+            # formatter
+            "W191",  # tab-indentation
+            "E111",  # indentation-with-invalid-multiple
+            "E114",  # indentation-with-invalid-multiple-comment
+            "E117",  # over-indented
+            "COM812",  # missing-trailing-comma
+            "COM819",  # prohibited-trailing-comma
+            "ISC001",  # single-line-implicit-string-concatenation
+            "ISC002",  # multi-line-implicit-string-concatenation
+        )
+        lint["preview"] = True
+        select = get_array(lint, "select")
+        selected_rules = [
+            "RUF022",  # unsorted-dunder-all
+            "RUF029",  # unused-async
+        ]
+        ensure_contains(select, "ALL", *selected_rules)
+        extend_per_file_ignores = get_table(lint, "extend-per-file-ignores")
+        test_py = get_array(extend_per_file_ignores, "test_*.py")
+        test_py_rules = [
+            "S101",  # assert
+            "SLF001",  # private-member-access
+        ]
+        ensure_contains(test_py, *test_py_rules)
+        ensure_not_contains(ignore, *selected_rules, *test_py_rules)
+        bugbear = get_table(lint, "flake8-bugbear")
+        extend_immutable_calls = get_array(bugbear, "extend-immutable-calls")
+        ensure_contains(extend_immutable_calls, "typing.cast")
+        tidy_imports = get_table(lint, "flake8-tidy-imports")
+        tidy_imports["ban-relative-imports"] = "all"
+        isort = get_table(lint, "isort")
+        req_imps = get_array(isort, "required-imports")
+        ensure_contains(req_imps, "from __future__ import annotations")
+        isort["split-on-trailing-comma"] = False
+
+
+##
+
+
+def check_versions() -> None:
+    version = get_version_from_bumpversion_toml()
+    try:
+        set_version(version)
+    except CalledProcessError:
+        msg = f"Inconsistent versions; should be {version}"
+        raise ValueError(msg) from None
+
+
+##
+
+
+def get_python_package_name(
+    *,
+    package_name: str | None = SETTINGS.package_name,
+    python_package_name: str | None = SETTINGS.python_package_name,
+) -> str | None:
+    if python_package_name is not None:
+        return python_package_name
+    if package_name is not None:
+        return package_name.replace("-", "_")
+    return None
+
+
+##
+
+
+def get_version_from_bumpversion_toml(
+    *, obj: TOMLDocument | str | None = None
+) -> Version:
+    match obj:
+        case TOMLDocument() as doc:
+            tool = get_table(doc, "tool")
+            bumpversion = get_table(tool, "bumpversion")
+            return parse_version(str(bumpversion["current_version"]))
+        case str() as text:
+            return get_version_from_bumpversion_toml(obj=tomlkit.parse(text))
+        case None:
+            with yield_bumpversion_toml() as doc:
+                return get_version_from_bumpversion_toml(obj=doc)
+        case never:
+            assert_never(never)
+
+
+def get_version_from_git_show() -> Version:
+    text = logged_run("git", "show", f"origin/master:{BUMPVERSION_TOML}", return_=True)
+    return get_version_from_bumpversion_toml(obj=text.rstrip("\n"))
+
+
+def get_version_from_git_tag() -> Version:
+    text = logged_run("git", "tag", "--points-at", "origin/master", return_=True)
+    for line in text.splitlines():
+        with suppress(ParseVersionError):
+            return parse_version(line)
+    msg = "No valid version from 'git tag'"
+    raise ValueError(msg)
+
+
+##
+
+
+def run_bump_my_version(*, modifications: MutableSet[Path] | None = None) -> None:
+    def run_set_version(version: Version, /) -> None:
+        LOGGER.info("Setting version to %s...", version)
+        set_version(version)
+        if modifications is not None:
+            modifications.add(BUMPVERSION_TOML)
+
+    try:
+        prev = get_version_from_git_tag()
+    except (CalledProcessError, ValueError):
+        try:
+            prev = get_version_from_git_show()
+        except (CalledProcessError, ParseVersionError, NonExistentKey):
+            run_set_version(Version(0, 1, 0))
+            return
+    current = get_version_from_bumpversion_toml()
+    patched = prev.bump_patch()
+    if current not in {patched, prev.bump_minor(), prev.bump_major()}:
+        run_set_version(patched)
+
+
+##
+
+
+def run_pre_commit_update(*, modifications: MutableSet[Path] | None = None) -> None:
+    cache = xdg_cache_home() / "conformalize" / get_repo_root().name
+    try:
+        text = cache.read_text()
+    except FileNotFoundError:
+        ...
+    else:
+        prev = ZonedDateTime.parse_iso(text.rstrip("\n"))
+        if prev >= (get_now() - 12 * HOUR):
+            return
+    write_text(cache, get_now().format_iso())
+    current = PRE_COMMIT_CONFIG_YAML.read_text()
+    logged_run("pre-commit", "autoupdate", print=True)
+    if (modifications is not None) and (PRE_COMMIT_CONFIG_YAML.read_text() != current):
+        modifications.add(PRE_COMMIT_CONFIG_YAML)
+
+
+##
+
+
+def run_ripgrep_and_replace(
+    *,
+    version: str = SETTINGS.python_version,
+    modifications: MutableSet[Path] | None = None,
+) -> None:
+    result = ripgrep(
+        "--files-with-matches",
+        "--pcre2",
+        "--type=py",
+        rf'# requires-python = ">=(?!{version})\d+\.\d+"',
+    )
+    if result is None:
+        return
+    for path in result.splitlines():
+        with yield_text_file(path, modifications=modifications) as context:
+            context.output = sub(
+                r'# requires-python = ">=\d+\.\d+"',
+                rf'# requires-python = ">={version}"',
+                context.input,
+                flags=MULTILINE,
+            )
+
+
+##
+
+
+def set_version(version: Version, /) -> None:
+    logged_run(
+        "bump-my-version",
+        "replace",
+        "--new-version",
+        str(version),
+        str(BUMPVERSION_TOML),
+    )
+
+
+##
+
+
+def update_action_file_extensions(
+    *, modifications: MutableSet[Path] | None = None
+) -> None:
+    try:
+        paths = list(Path(".github").rglob("**/*.yml"))
+    except FileNotFoundError:
+        return
+    for path in paths:
+        new = path.with_suffix(".yaml")
+        LOGGER.info("Renaming '%s' -> '%s'...", path, new)
+        _ = path.rename(new)
+        if modifications is not None:
+            modifications.add(path)
+
+
+##
+
+
+def update_action_versions(*, modifications: MutableSet[Path] | None = None) -> None:
+    try:
+        paths = list(Path(".github").rglob("**/*.yaml"))
+    except FileNotFoundError:
+        return
+    versions = {
+        "actions/checkout": "v6",
+        "actions/setup-python": "v6",
+        "astral-sh/ruff-action": "v3",
+        "astral-sh/setup-uv": "v7",
+    }
+    for path, (action, version) in product(paths, versions.items()):
+        text = sub(
+            rf"^(\s*- uses: {action})@.+$",
+            rf"\1@{version}",
+            path.read_text(),
+            flags=MULTILINE,
+        )
+        with yield_yaml_dict(path, modifications=modifications) as dict_:
+            dict_.clear()
+            dict_.update(YAML_INSTANCE.load(text))
+
+
+##
+
+
+@contextmanager
+def yield_bumpversion_toml(
+    *, modifications: MutableSet[Path] | None = None
+) -> Iterator[TOMLDocument]:
+    with yield_toml_doc(BUMPVERSION_TOML, modifications=modifications) as doc:
+        tool = get_table(doc, "tool")
+        bumpversion = get_table(tool, "bumpversion")
+        bumpversion["allow_dirty"] = True
+        bumpversion.setdefault("current_version", str(Version(0, 1, 0)))
+        yield doc
+
+
+##
+
+
+def yield_python_versions(
+    version: str, /, *, max_: str = MAX_PYTHON_VERSION
+) -> Iterator[str]:
+    major, minor = _yield_python_version_tuple(version)
+    max_major, max_minor = _yield_python_version_tuple(max_)
+    if major != max_major:
+        msg = f"Major versions must be equal; got {major} and {max_major}"
+        raise ValueError(msg)
+    if minor > max_minor:
+        msg = f"Minor version must be at most {max_minor}; got {minor}"
+        raise ValueError(msg)
+    for i in range(minor, max_minor + 1):
+        yield f"{major}.{i}"
+
+
+def _yield_python_version_tuple(version: str, /) -> tuple[int, int]:
+    major, minor = extract_groups(r"^(\d+)\.(\d+)$", version)
+    return int(major), int(minor)
+
+
+##
+
+
+__all__ = [
+    "add_bumpversion_toml",
+    "add_coveragerc_toml",
+    "add_envrc",
+    "add_github_pull_request_yaml",
+    "add_github_push_yaml",
+    "add_gitignore",
+    "add_pre_commit_config_yaml",
+    "add_pyproject_toml",
+    "add_pyrightconfig_json",
+    "add_pytest_toml",
+    "add_readme_md",
+    "add_ruff_toml",
+    "check_versions",
+    "get_python_package_name",
+    "get_version_from_bumpversion_toml",
+    "get_version_from_git_show",
+    "get_version_from_git_tag",
+    "run_bump_my_version",
+    "run_pre_commit_update",
+    "run_ripgrep_and_replace",
+    "set_version",
+    "update_action_file_extensions",
+    "update_action_versions",
+    "yield_bumpversion_toml",
+    "yield_python_versions",
+]