Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

61.4 KB
Raw Blame
#!/usr/bin/env python3
"""Move the Python package to a new directory and rewrite every reference to it.

One mechanical step, so the commit that renames the package is exactly this
script's output and any branch can replay it instead of resolving conflicts::

    python scripts/rename/rewrite_package.py --from jarvis --to dodaios --dry-run
    python scripts/rename/rewrite_package.py --from jarvis --to dodaios
    python scripts/rename/rewrite_package.py --from jarvis --to dodaios --check

What a run does, in order:

1. **Move** every tracked file of ``<from>/`` to ``<to>/`` with ``git mv``
   (the frontend source and its built bundle live inside the package and move
   with it).
2. **Rewrite** the references in every tracked text file: imports, dotted
   module paths (``-m <from>.ui.web.launcher``, ``importlib`` and patch
   targets, entry-point TARGETS, logger names) and filesystem paths
   (``<from>/core/x.py`` in workflows, CI path filters, packaging scripts,
   allowlists, docs).
3. **Write the compatibility package** ``<from>/__init__.py``: old start
   commands and old imports keep working and resolve to the SAME module
   objects as the new name.
4. **Stage** exactly the paths it touched.

Only the lowercase package name is ever a candidate, and only where it is
provably the package: a dotted name is rewritten when its first segment is a
real module of the package, a path when its first segment is a real entry of
the package directory. Everything that merely contains the old name stays -
see ``LEGACY_IDENTIFIERS``, ``FROZEN_FILES`` and ``UNRESOLVED_PATHS_KEPT``, the
tables that say what is deliberately left alone and why. A hit the rules
cannot decide is never touched; ``--dry-run`` lists it with ``file:line`` for
a person to decide, and ``--explain RULE`` lists every decision one rule made.
A line that carries the words ``rename-keep`` is skipped entirely.

The script is one stdlib-only file on purpose: branch integration
(``scripts/ci/agent_integrate.py``) loads the version that produced the move
commit straight from that commit and applies it to a branch's own changes.
"""

from __future__ import annotations

import argparse
import ast
import bisect
import fnmatch
import json
import os
import re
import subprocess
import sys
from collections import Counter
from collections.abc import Iterable
from dataclasses import dataclass, field
from pathlib import Path

#: Put these words on a line to keep the codemod away from it.
KEEP_PRAGMA = "rename-keep"
#: First-line marker of the generated compatibility package. A file that
#: carries it is never moved and never rewritten.
STUB_MARKER = "rename-stub: generated by scripts/rename/rewrite_package.py"
#: ``__version__`` of the compatibility package. Updaters that predate the
#: rename read the version out of ``<from>/__init__.py`` as text; a value that
#: matches no release makes them stop cleanly instead of looping. Importing
#: the package still reports the real version (the module is the new one).
STUB_VERSION = "0.0.0"

_NO_WINDOW = getattr(subprocess, "CREATE_NO_WINDOW", 0) if os.name == "nt" else 0


# --------------------------------------------------------------------------- tables


@dataclass(frozen=True)
class Legacy:
    """One identifier that keeps the old name on purpose."""

    name: str
    reason: str
    #: Regex over the file text, ``{old}`` standing for the escaped package
    #: name. A candidate inside a match is kept. ``None`` = the identifier is
    #: protected by a structural rule named in ``reason`` (or never contains
    #: the lowercase name at all) and is listed here for the record and tests.
    pattern: str | None
    #: Text that must come through a run byte-identical (the unit tests feed
    #: every sample through the rewriter).
    samples: tuple[str, ...]


LEGACY_IDENTIFIERS: tuple[Legacy, ...] = (
    Legacy(
        "config file",
        "jarvis.toml / jarvis.toml.example are the user's configuration file; it is renamed "
        "with a migration by the identifier stage, never by a search and replace.",
        r"{old}\.toml\b",
        ('CONFIG = root / "jarvis.toml"', "cp jarvis.toml.example jarvis.toml", "/jarvis.toml"),
    ),
    Legacy(
        "database file",
        "jarvis.db lives in the data directory; renaming a database is not atomic.",
        r"{old}\.db\b",
        ('db = data_dir / "jarvis.db"', "data/jarvis.db-wal"),
    ),
    Legacy(
        "instance lock",
        "jarvis.lock is the lock an old and a new version share; both must agree on its name.",
        r"{old}\.lock\b",
        ('LOCK = data_dir / "jarvis.lock"',),
    ),
    Legacy(
        "desktop log",
        "jarvis_desktop.log is a file inside the data directory (structural: the name is "
        "followed by an underscore).",
        r"{old}_desktop\b",
        ("tail data/jarvis_desktop.log", "jarvis_desktop.2026-07-05_1.log"),
    ),
    Legacy(
        "PyInstaller spec file name",
        "jarvis.spec stays where it is: the build file is a projection of the technical "
        "identifiers and is renamed with them, not with the package. Its CONTENT is rewritten.",
        r"{old}\.spec\b",
        ("pyinstaller jarvis.spec --noconfirm", '"jarvis.spec",'),
    ),
    Legacy(
        "MCP tool prefix",
        "mcp__jarvis__ is a wire name other agents have stored in their permission lists.",
        r"mcp__{old}__",
        ('"mcp__jarvis__society_status"',),
    ),
    Legacy(
        "URL scheme",
        "jarvis:// links are stored in user data and registered with the OS.",
        r"{old}://",
        ('href="jarvis://open/chat"',),
    ),
    Legacy(
        "control key prefix",
        "jctl_ prefixes issued control keys; it does not contain the package name.",
        None,
        ('key = "jctl_" + token',),
    ),
    Legacy(
        "session cookie",
        "jarvis_session is the browser cookie; renaming it signs every user out (structural: "
        "underscore).",
        r"{old}_session\b",
        ('COOKIE = "jarvis_session"',),
    ),
    Legacy(
        "managed-install marker",
        ".jarvis-managed-install and the .jarvis-update-* markers are files older versions "
        "look for (structural: leading dot and hyphen).",
        r"\.{old}-[a-z]",
        ("touch .jarvis-managed-install", '".jarvis-update-pending.json"'),
    ),
    Legacy(
        "environment variables",
        "Every JARVIS_* / JARVIS__* variable keeps working; the uppercase name is never a "
        "candidate because only the lowercase package name is.",
        None,
        ("JARVIS_CONFIG=/app/data/jarvis.toml", 'os.environ["JARVIS__BRAIN__PROVIDER"]'),
    ),
    Legacy(
        "console script names",
        "The commands jarvis, jarvisctl, jctl, personal-jarvis, jarvis-review-gc stay; only "
        "their TARGETS move (structural: a bare name or a compound with a hyphen).",
        None,
        (
            "jarvis = ",
            "personal-jarvis = ",
            "jarvis-review-gc = ",
            "Run `jarvis serve` or `jarvisctl missions list`.",
        ),
    ),
    Legacy(
        "entry-point groups",
        "jarvis.stt, jarvis.tool, ... are plugin group names installed plugins declare; the "
        "additive stage adds the new groups next to them. A group that shares its name with "
        "a module (jarvis.brain) is told apart by context and reported when that fails. "
        "jarvis.<group> and jarvis.<slot> are how a document writes any group at all.",
        r"entry[-_]points?\W{{0,3}}[\"']{old}\.[a-z_<>*]+[\"']"
        r"|\bgroup\s*=\s*[\"']{old}\.[a-z_]+[\"']"
        r"|entry_points(?:_for)?\(\s*[\"']{old}\.[a-z_]+[\"']"
        r"|{old}\.<(?:group|slot)>",
        (
            '[project.entry-points."jarvis.brain"]',
            '[project.entry-points."jarvis.<group>"]',
            'entry_points(group="jarvis.tool")',
            'entry_points_for("jarvis.stt")',
            "the earlier `jarvis.<group>` name stays valid",
            "every plugin written before the rename registers as ``jarvis.<slot>``",
        ),
    ),
    Legacy(
        "Docker volume",
        "jarvis-data is the named volume holding a Docker user's data (structural: hyphen).",
        r"{old}-data\b",
        ("-v jarvis-data:/app/data",),
    ),
    Legacy(
        "openclaw strings",
        "The external binary name and its read-time aliases are load-bearing and do not "
        "contain the package name.",
        None,
        ('RUNTIME = "openclaw"', "spawn-openclaw"),
    ),
    Legacy(
        "legacy lists",
        "LEGACY_* / RETIRED_* assignments record former values on purpose; nothing inside "
        "one is rewritten (structural: the whole assignment is protected).",
        None,
        (
            'LEGACY_LAUNCHER_MODULES = ("jarvis.ui.web.launcher", "jarvis.ui.relauncher")',
            '_RETIRED_BUNDLE_DIRS = [\n    "jarvis/ui/web/dist",\n]',
        ),
    ),
    Legacy(
        "data directories",
        "~/.jarvis and %LOCALAPPDATA%\\Jarvis are moved by the migration module (structural: "
        "leading dot; the capitalised name is never a candidate).",
        r"\.{old}\b",
        ('home / ".jarvis" / "skills"', "~/.jarvis/agent_runtimes", "%LOCALAPPDATA%\\Jarvis"),
    ),
    Legacy(
        "config and vault folders",
        "~/.config/jarvis holds the credentials on a remote machine and society/jarvis is "
        "the vault folder of the agent named Jarvis. Both are data, even where the next "
        "segment happens to be a folder the package also has (workspace, memory, skills).",
        r"(?:\.config|society)[/\\]{{1,2}}{old}\b",
        (
            "~/.config/jarvis/agent.env",
            'workspaceDir: "society/jarvis/workspace"',
            "vault / society/jarvis/memory/notes.md",
            "the convention path ~/.config/jarvis/...",
        ),
    ),
    Legacy(
        "assistant name and wake word",
        'The assistant is called whatever the user chose; "Jarvis" in prose, prompts and '
        "speech vocabulary is a name, not the package (structural: a bare or capitalised "
        "name is not a module path).",
        None,
        ('WAKE_WORDS = ("jarvis", "hey jarvis")', "Hey Jarvis, what is on today?"),
    ),
    Legacy(
        "wire and storage names",
        "HTTP headers, storage keys, manifest ids, distribution and artifact names "
        "(structural: compound with a hyphen, underscore or colon).",
        r"x-{old}-|{old}:[a-z]",
        (
            '"x-jarvis-dangerous": True',
            "x_jarvis_sig",
            'localStorage.getItem("jarvis:theme")',
            "io.github.personaljarvis",
            "pip install personal-jarvis",
        ),
    ),
)


@dataclass(frozen=True)
class Frozen:
    """A file (or tree) whose CONTENT is never rewritten. It still moves."""

    glob: str
    reason: str


#: Shell-style patterns; ``{pkg}`` stands for the package directory under
#: either name, so a file is frozen before the move and after it.
FROZEN_FILES: tuple[Frozen, ...] = (
    Frozen("CHANGELOG.md", "release history: it says what a version shipped, under its old paths"),
    Frozen("docs/supply-chain/**", "signed-release evidence, kept as it was recorded"),
    Frozen("docs/superpowers/**", "dated plans and specs, kept as they were written"),
    Frozen("{pkg}/ui/web/dist/**", "generated bundle: moved as is, `npm run build` rewrites it"),
    Frozen("{pkg}/ui/web/frontend/src/i18n/**", "i18n texts are product copy, not references"),
    Frozen(
        "{pkg}/marketplace/seed_catalog.json",
        "stored plugin configuration: an entry starts its bundled server by module name "
        "(`python -m <old>.plugins.tool.connected_server`), that command is copied into "
        "every install's catalog override and is part of the `config_fingerprint` the "
        "browser evidence in docs/marketplace/plugin-e2e-audit.json is bound to. Rewritten, "
        "it would make that evidence stale and every stored command differ from the "
        "catalog; the compatibility package keeps the old module names starting",
    ),
    Frozen(
        "{pkg}/marketplace/plugins/**",
        "the agent-plugin form of the same catalog entries: every manifest repeats its "
        "entry's server command and has to stay equal to it",
    ),
    Frozen("**/package-lock.json", "lockfile, regenerated"),
    Frozen("uv.lock", "lockfile, regenerated"),
    Frozen("scripts/rename/**", "this codemod: its tables name the old identifiers as data"),
    Frozen("tests/unit/ci/test_rewrite_package.py", "the codemod's tests, same reason"),
    Frozen("tests/unit/ci/test_package_move_integration.py", "the replay tests, same reason"),
)


@dataclass(frozen=True)
class LocalPrefix:
    """Files where ``<old>/<something>`` that is NOT a path of the package is
    a prefix of another kind, and stays."""

    glob: str
    reason: str
    #: The names right below ``<old>/`` this entry is about. Empty: every
    #: unresolved one in the file. Named: only those, so a path to a removed
    #: module in the same document is still rewritten.
    names: tuple[str, ...] = ()


UNRESOLVED_PATHS_KEPT: tuple[LocalPrefix, ...] = (
    LocalPrefix(
        "{pkg}/agentic_ide/remote.py",
        "jarvis/<computer>/<time> names the git branch a remote pane's work comes back on",
    ),
    LocalPrefix("tests/unit/agentic_ide/test_remote_*.py", "the same branch prefix, asserted"),
    LocalPrefix(
        "board-backend/README.md",
        "`cd jarvis/board-backend` enters the folder a shell example cloned the repository into",
        ("board-backend",),
    ),
    LocalPrefix(
        "docs/agent-society/build-plan-m1-m2.md",
        "`jarvis/agent session lists` names two chat surfaces, not a path",
        ("agent",),
    ),
    LocalPrefix(
        "docs/agent-society/research/branch-a-product-ui.md",
        "the same tombstone",
        ("sub_jarvis",),
    ),
)

#: Entry-point group suffixes known without a pyproject (the real list is read
#: from ``[project.entry-points."<old>.<group>"]`` and added to these).
_KNOWN_GROUPS = frozenset(
    {"wakeword", "turn", "stt", "tts", "brain", "harness", "channel", "realtime", "tool"}
)

#: Web sources keep storage keys such as ``<old>.setup.walkStop`` and tool
#: prefixes such as ``<old>/gmail`` that look exactly like module paths and
#: package paths; there a name must resolve two levels deep to be rewritten.
_WEB_SUFFIXES = frozenset({".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".html", ".css", ".vue"})
#: A path that ends like a source file is a path of the package even when the
#: file does not exist (a removed module in a document, a made-up one in a test).
_SOURCE_SUFFIXES = (
    "py|pyi|md|json|toml|ts|tsx|js|css|html|sql|txt|yaml|yml|sh|ps1|c|mjs|png|svg|ico|onnx|patch"
)

_IDENT = r"[A-Za-z_][A-Za-z0-9_]*"
#: ``.name`` segments; ``\.`` and ``\\.`` are the same path inside a regex.
_CHAIN_RE = re.compile(rf"((?:\\{{0,2}}\.{_IDENT})+)")
_CHAIN_SEGMENT_RE = re.compile(rf"\\{{0,2}}\.({_IDENT})")
_SEGMENT_RE = re.compile(r"\.?[A-Za-z0-9_][A-Za-z0-9_.\-]*")
_PATH_TOKEN_RE = re.compile(r"[A-Za-z0-9_./\\-]*")
# ``\r?``: a checkout with CRLF line endings decides exactly like one with LF.
_TOML_SECTION_RE = re.compile(r"^\[+([^\]\n]+)\]+[ \t]*(?:#[^\n]*)?\r?$", re.MULTILINE)
_LEGACY_ASSIGN_RE = re.compile(
    r"^[ \t]*(?:[A-Za-z_][\w.]*\.)?\w*(?:LEGACY|RETIRED)\w*[ \t]*(?::[^=\n]*)?=(?!=)",
    re.MULTILINE | re.IGNORECASE,
)
# Calls and subscripts whose string argument is an importable name.
_IMPORTING_CALL_RE = re.compile(
    r"(?:getLogger|import_module|find_spec|__import__|files|as_file|get_data|"
    r"collect_submodules|collect_data_files|collect_all|collect_dynamic_libs|"
    r"sys\.modules(?:\.get|\.pop)?|importorskip|resolve_name|patch(?:\.object|\.dict)?|"
    r"setitem|delitem|setattr|delattr)\s*[\(\[]\s*(?:sys\.modules\s*,\s*)?[rbf]*[\"']$"
)
_IMPORT_STMT_RE = re.compile(r"(?:^|[\s;:\"'`(>])(?:import|from)\s+$")
_FROM_RE = re.compile(r"\bfrom\s+$")
_IMPORT_REGEX_RE = re.compile(r"(?:import|from)\W{0,6}\\s[+*]$")
_IMPORT_WORD_RE = re.compile(r"\bimport(?:s|ed|ing)?\b", re.IGNORECASE)
_DASH_M_RE = re.compile(r"(?:^|[\s\"'`\[(,=])-m(?:\s+|[\"']\s*,\s*[\"'])$")
_TOOL_DIR_RE = re.compile(
    r"(?:\bruff(?:\s+(?:check|format))?|\bmypy|\bbandit|\bpyright|\bvulture|\bpylint|"
    r"--cov|\bcoverage\s+run|--source)\b[^\n|;&]*[\s=,]$"
)
_GROUP_WORD_RE = re.compile(r"entry[-_ ]?points?|group", re.IGNORECASE)
_PACKAGE_DATA_SECTIONS = ("tool.setuptools.package-data", "tool.setuptools.exclude-package-data")
# The operand left of a ``/`` or ``,`` that puts a quoted name into a path.
_JOIN_LEFT_RE = re.compile(r"([\"'\w)\]])\s*(?:/|,)\s*$")
_JOIN_CALL_RE = re.compile(r"\b(?:join|joinpath|Path|PurePath|PurePosixPath)\(")
_BIN_OPERAND_RE = re.compile(r"(?i)(?:\bbin|scripts)\w*\s*(?:/|,)\s*$")
# ``_ROOTS = ("<old>", "scripts")``, ``for root in ("<old>", "tests")``: the
# directories a gate walks.
_DIRECTORY_LIST_RE = re.compile(
    r"(?i)^\s*(?:\w*(?:roots|dirs|directories|trees)\b[^=\n]*=|for\s+\w*(?:root|dir|tree)\w*\s+in\b)"
    r"[^=\n]*$"
)
_DASH_M_LEFT_RE = re.compile(r"[\"']-m[\"']\s*,\s*$")
# ``name.startswith("<old>")``: module names, command names, branch names ...
_PREFIX_TEST_RE = re.compile(r"\bstartswith\(\s*\(?\s*[rbf]*[\"']$")
# A lookup in setuptools' package-data table, whose key is the package:
# ``cfg["package-data"]["<old>"]``, ``cfg.get("package-data", {}).get("<old>")``,
# or the same through a variable the table was assigned to.
_PACKAGE_DATA_LOOKUP_RE = re.compile(r"package[-_]data[\"'][^\n\"']{0,12}(?:\[|\.get\()\s*[\"']$")
_PACKAGE_DATA_ASSIGN_RE = re.compile(
    r"^[ \t]*(\w+)[ \t]*(?::[^=\n]*)?=[^=\n][^\n]*package[-_]data[\"'][^\n]*$", re.MULTILINE
)
_LOOKUP_ON_NAME_RE = re.compile(r"\b(\w+)(?:\[|\.get\()\s*[\"']$")
# What follows a quoted name in a path: ``/ "core"`` or ``, "core"``.
_FOLLOWER_RE = re.compile(r"\s*\)*\s*(/|,)\s*[rf]?[\"']([^\"'/\\\n]+)[\"']")


# --------------------------------------------------------------------------- git


def _git(root: Path, *args: str, stdin: bytes | None = None) -> subprocess.CompletedProcess[bytes]:
    return subprocess.run(  # noqa: S603
        ["git", *args],  # noqa: S607
        cwd=root,
        input=stdin,
        capture_output=True,
        check=False,
        creationflags=_NO_WINDOW,
    )


def tracked_files(root: Path) -> list[tuple[str, str]]:
    """Every tracked path with its git mode, sorted. Conflict stages collapse."""
    proc = _git(root, "ls-files", "-s", "-z")
    if proc.returncode != 0:
        raise SystemExit(f"not a git checkout: {root}\n{proc.stderr.decode('utf-8', 'replace')}")
    seen: dict[str, str] = {}
    for record in proc.stdout.decode("utf-8", "surrogateescape").split("\0"):
        if not record:
            continue
        meta, _, path = record.partition("\t")
        seen.setdefault(path, meta.split(" ", 1)[0])
    return sorted(seen.items())


# --------------------------------------------------------------------------- rewriting


@dataclass(frozen=True)
class Hit:
    """One candidate the rules could not decide, or one reported decision."""

    path: str
    line: int
    column: int
    reason: str
    excerpt: str

    def render(self) -> str:
        return f"{self.path}:{self.line}:{self.column}: {self.reason}: {self.excerpt}"


@dataclass
class FileResult:
    path: str
    rewrites: Counter[str] = field(default_factory=Counter)
    ambiguous: list[Hit] = field(default_factory=list)
    explained: list[Hit] = field(default_factory=list)

    @property
    def changed(self) -> bool:
        return bool(self.rewrites)


def _statement_end(text: str, start: int) -> int:
    """End of the statement that starts at ``start``: the rest of the line, or
    through the bracket that opens on it."""
    depth = 0
    quote = ""
    index = start
    while index < len(text):
        char = text[index]
        if quote:
            if char == "\\":
                index += 1
            elif text.startswith(quote, index):
                index += len(quote) - 1
                quote = ""
        elif char in "\"'":
            quote = char * 3 if text.startswith(char * 3, index) else char
            index += len(quote) - 1
        elif char == "#":
            newline = text.find("\n", index)
            if newline == -1:
                return len(text)
            index = newline - 1
        elif char in "([{":
            depth += 1
        elif char in ")]}":
            depth -= 1
        elif char == "\n" and depth <= 0:
            return index
        index += 1
    return len(text)


Decision = tuple[str, str]  # (action, rule); action is rewrite | keep | ambiguous


class Rewriter:
    """Decides, for one occurrence of the old name at a time, whether it is
    the package - and rewrites the ones that provably are."""

    def __init__(
        self,
        old: str,
        new: str,
        paths: Iterable[str],
        groups: Iterable[str] = (),
    ) -> None:
        if not re.fullmatch(_IDENT, old) or not re.fullmatch(_IDENT, new):
            raise ValueError("package names must be plain identifiers")
        if old == new or old.lower() != old or new.lower() != new:
            raise ValueError("package names must differ and be lowercase")
        if old in new or new in old:
            raise ValueError("one package name contains the other; a run could not be repeated")
        self.old = old
        self.new = new
        entries: set[str] = set()
        nested: set[str] = set()
        for path in paths:
            parts = path.split("/")
            entries.add(parts[0])
            if len(parts) > 1:
                nested.add(f"{_stem(parts[0])}.{_stem(parts[1])}")
        #: Names directly inside the package directory (``core``, ``__main__.py``).
        self.entries = frozenset(entries)
        #: The same as importable names (``core``, ``__main__``).
        self.modules = frozenset(_stem(entry) for entry in entries)
        #: Two-level importable names (``core.config``, ``ui.web``).
        self.submodules = frozenset(nested)
        self.groups = frozenset(groups) | _KNOWN_GROUPS
        #: Rule names whose every decision is listed (``--explain``).
        self.explain: frozenset[str] = frozenset()
        escaped = re.escape(old)
        # A candidate: the lowercase name with no letter or digit on either
        # side. ``\b<old>`` inside a regular expression counts as a boundary.
        self._token = re.compile(rf"(?:(?<![A-Za-z0-9])|(?<=\\b)){escaped}(?![A-Za-z0-9])")
        # Where a Python file can bind the name as a variable of its own.
        self._binding = re.compile(
            rf"(?<![.\w\"'/]){escaped}\s*(?:=[^=]|:|,|\)|\bin\b)|\bas\s+{escaped}\b"
            rf"|\b(?:def|class|for)\s+{escaped}\b|[(,]\s*\*{{0,2}}{escaped}\s*[,):=]"
        )
        # A path below the package that names a file which is not there.
        self._made_up_path = re.compile(
            rf"(?<![A-Za-z0-9_./\\-]){escaped}/([A-Za-z0-9_]+)[A-Za-z0-9_./-]*"
            rf"\.(?:{_SOURCE_SUFFIXES})\b"
            rf"|[\"']{escaped}[\"']\s*/\s*[\"']([A-Za-z0-9_]+)"
        )
        self._legacy = [
            (re.compile(entry.pattern.format(old=escaped)), entry.name)
            for entry in LEGACY_IDENTIFIERS
            if entry.pattern
        ]
        self._frozen = _for_packages((frozen.glob for frozen in FROZEN_FILES), old, new)
        self._kept_prefixes = [
            (pattern, kept.names)
            for kept in UNRESOLVED_PATHS_KEPT
            for pattern in _for_packages((kept.glob,), old, new)
        ]

    # ----- construction from a checkout

    @classmethod
    def from_tree(cls, root: Path, old: str, new: str) -> Rewriter:
        """Read the package's layout and entry-point groups from ``root``.

        Both directories count, so a run before the move, a run after it and a
        replay on a branch that added a module all resolve the same names.
        """
        paths = [
            path.split("/", 1)[1]
            for path, _mode in tracked_files(root)
            if path.startswith((old + "/", new + "/"))
        ]
        groups: set[str] = set()
        pyproject = root / "pyproject.toml"
        if pyproject.is_file():
            text = pyproject.read_text(encoding="utf-8", errors="replace")
            pattern = rf'entry-points\.["\'](?:{re.escape(old)}|{re.escape(new)})\.([A-Za-z0-9_]+)'
            groups.update(re.findall(pattern, text))
        return cls(old, new, paths, groups)

    # ----- paths

    def map_path(self, path: str) -> str:
        """Where a tracked path lives after the move."""
        if path.startswith(self.old + "/"):
            return self.new + path[len(self.old) :]
        return path

    def is_frozen(self, path: str) -> bool:
        return any(fnmatch.fnmatchcase(path, pattern) for pattern in self._frozen)

    def keeps_unresolved_paths(self, path: str, name: str = "") -> bool:
        """True when ``<old>/<name>`` in the file at ``path`` is a prefix of
        another kind (``UNRESOLVED_PATHS_KEPT``)."""
        return any(
            fnmatch.fnmatchcase(path, pattern) and (not names or name in names)
            for pattern, names in self._kept_prefixes
        )

    def resolves(self, name: str) -> bool:
        """True when ``name`` is an entry of the package directory."""
        name = name.rstrip(".")
        return name in self.entries or name in self.modules

    # ----- one file

    def transform(self, path: str, data: bytes) -> bytes:
        """The rewritten bytes of one file (unchanged when nothing applies)."""
        return self.rewrite(path, data)[0]

    def rewrite(self, path: str, data: bytes) -> tuple[bytes, FileResult]:
        result = FileResult(path)
        if self.is_frozen(path) or b"\0" in data[:8192] or self.old.encode() not in data:
            return data, result
        if STUB_MARKER.encode() in data[:400]:
            return data, result
        try:
            text = data.decode("utf-8")
        except UnicodeDecodeError:
            return data, result
        text = self._line_rules(path, text, result)
        state = _FileState(self, path, text)
        pieces: list[str] = []
        cursor = 0
        for match in self._token.finditer(text):
            start, end = match.span()
            action, rule = self._decide(state, start, end)
            if self.explain and (rule in self.explain or "*" in self.explain):
                result.explained.append(state.hit(start, f"{action} [{rule}]"))
            if action == "rewrite":
                pieces.append(text[cursor:start])
                pieces.append(self.new)
                cursor = end
                result.rewrites[rule] += 1
            elif action == "ambiguous":
                result.ambiguous.append(state.hit(start, rule))
        pieces.append(text[cursor:])
        return "".join(pieces).encode("utf-8"), result

    # ----- whole-line rules (the two places where a run adds something)

    def _line_rules(self, path: str, text: str, result: FileResult) -> str:
        old, new = re.escape(self.old), self.new
        name = path.rsplit("/", 1)[-1]
        if name in ("pyproject.toml", "setup.cfg"):
            # The compatibility package ships next to the real one.
            pattern = re.compile(
                rf'^([ \t]*include[ \t]*=[ \t]*\[)([^\]\n]*"{old}\*"[^\]\n]*\])', re.MULTILINE
            )

            def add_package(match: re.Match[str]) -> str:
                if f'"{new}*"' in match.group(2):
                    return match.group(0)
                result.rewrites["package discovery"] += 1
                return f'{match.group(1)}"{new}*", {match.group(2)}'

            text = pattern.sub(add_package, text)
        if name == "Dockerfile" or name.startswith("Dockerfile."):
            # The image needs both directories: the package and its old name.
            pattern = re.compile(rf"(COPY[ \t]+(?:--\S+[ \t]+)*){old}([ \t]+\./){old}/?[ \t]*\r?")
            lines = text.split("\n")
            for index, line in enumerate(lines):
                match = pattern.fullmatch(line)
                if not match or KEEP_PRAGMA in line:
                    continue
                twin = f"{match.group(1)}{new}{match.group(2)}{new}"
                if index and lines[index - 1].rstrip("\r") == twin:
                    continue
                ending = "\r" if line.endswith("\r") else ""
                lines[index] = f"{twin}{ending}\n{line}"
                result.rewrites["image copy"] += 1
            text = "\n".join(lines)
        return text

    # ----- one occurrence

    def _decide(self, state: _FileState, start: int, end: int) -> Decision:
        text = state.text
        prev = text[start - 1] if start else ""
        nxt = text[end : end + 1]
        line_start, line_end = state.line_span(start)
        # Long single-line files (reports, data) would make every look-around
        # a scan of the whole line.
        before = text[max(line_start, start - 240) : start]
        after = text[end : min(line_end, end + 240)]

        if text.find(KEEP_PRAGMA, line_start, line_end) != -1:
            return "keep", "pragma"
        legacy = state.legacy_at(start, end)
        if legacy:
            return "keep", legacy
        if state.in_legacy_assignment(start):
            return "keep", "legacy lists"
        # <old>_desktop.log, personal-<old>, x_<old>_sig.
        if prev in ("_", "-") or nxt in ("_", "-"):
            return "keep", "compound identifier"
        # .<old> is a data directory or an attribute of something else.
        if prev == ".":
            return "keep", "dotted suffix"
        if text.startswith("://", end) or (nxt == ":" and text[end + 1 : end + 2].isalpha()):
            return "keep", "scheme or storage prefix"

        if nxt == "." or text.startswith(("\\.", "\\\\."), end):
            return self._decide_dotted(state, start, end, before, after)
        if nxt in ("/", "\\"):
            decision = self._decide_path(state, start, end, prev)
            if decision is not None:
                return decision
        if nxt == "*":
            return "keep", "glob"
        return self._decide_bare(state, start, end, prev, before, after)

    def _decide_dotted(
        self, state: _FileState, start: int, end: int, before: str, after: str
    ) -> Decision:
        chain = _CHAIN_RE.match(state.text, end)
        if chain is None:
            tail = after[1:2]
            if tail == "*":
                return "rewrite", "module wildcard"
            if tail in ("<", "{", "["):
                return "ambiguous", "placeholder: a module of the package, or a plugin group"
            quote = state.text[start - 1 : start]
            if state.is_python and quote in ("'", '"') and tail == quote:
                # ``name.startswith("<old>.")``: a guard over imported module
                # names stops guarding once the modules carry the new name.
                return "ambiguous", "quoted prefix: of module names, or of something else"
            return "keep", "end of sentence"
        segments = _CHAIN_SEGMENT_RE.findall(chain.group(1))
        first = segments[0]
        dunder = first.startswith("__") and first.endswith("__")
        if not dunder and first not in self.modules:
            return "keep", "not a module of the package"
        if state.is_local_name(start):
            return "ambiguous", "a local variable carries the package's name here"
        if dunder:
            return "rewrite", "package attribute"
        if state.is_web:
            if len(segments) > 1 and f"{first}.{segments[1]}" in self.submodules:
                return "rewrite", "module path"
            return "keep", "web source: storage key or group"
        if len(segments) == 1 and first in self.groups:
            if state.text.startswith(".*", chain.end()):
                return "rewrite", "module wildcard"
            return self._decide_group_or_module(state, start, before, chain.end())
        return "rewrite", "module path"

    def _decide_group_or_module(
        self, state: _FileState, start: int, before: str, chain_end: int
    ) -> Decision:
        """``<old>.brain`` is a plugin group AND a module; context tells."""
        tail = state.text[chain_end : chain_end + 16]
        if _IMPORT_STMT_RE.search(before) or re.match(r"\s+import\b", tail):
            return "rewrite", "import"
        if re.match(rf":{_IDENT}", tail):
            return "rewrite", "entry-point target"
        if _IMPORTING_CALL_RE.search(before) or _DASH_M_RE.search(before):
            return "rewrite", "importable name"
        if state.is_python_code_token(start):
            return "rewrite", "module path"
        line = state.line(start)
        if _GROUP_WORD_RE.search(line):
            return "keep", "entry-point groups"
        if _IMPORT_WORD_RE.search(line) or state.has_module_path(line):
            return "ambiguous", "plugin group or module of the same name"
        return "keep", "entry-point groups"

    def _decide_path(self, state: _FileState, start: int, end: int, prev: str) -> Decision | None:
        text = state.text
        separator = re.match(r"/|\\{1,2}", text[end : end + 2])
        if separator is None:
            return None
        rest_at = end + separator.end()
        rest = text[rest_at : rest_at + 160]
        segment = _SEGMENT_RE.match(rest)
        name = segment.group(0).rstrip(".") if segment else ""
        if name and self.resolves(name):
            return "rewrite", "package path"
        if separator.group(0) == "\\" and re.match(r"[bBsSdDwWnrtAZ.()\[\]|$^?+*]", rest):
            return None  # ``<old>\b`` in a regular expression, ``<old>\n`` in a string
        if state.is_web:
            return "keep", "web source: tool prefix"
        if self.keeps_unresolved_paths(state.path, name):
            return "keep", "prefix of another kind"
        # ``a/<old>/x.py`` and ``b/<old>/x.py`` in a diff are the path itself.
        in_diff = re.search(r"(?:^|[\s\"'`])[ab]/$", text[max(0, start - 3) : start]) is not None
        below_another = prev in ("/", "\\") and not in_diff
        if rest.startswith("..."):
            return "rewrite", "package path"
        if not name:
            opener = rest[:1]
            if below_another:
                return "ambiguous", "directory of this name below another directory"
            if opener == "{":
                first = re.match(r"\{([A-Za-z0-9_]+),", rest)
                if first and self.resolves(first.group(1)):
                    return "rewrite", "package path"
            if opener in ("{", "<", "$", "%"):
                return "ambiguous", "placeholder below the name: a package path, or another prefix"
            return "rewrite", "package directory"
        if below_another:
            return "keep", "directory of this name elsewhere"
        token = _PATH_TOKEN_RE.match(rest).group(0).rstrip(".")  # type: ignore[union-attr]
        if re.search(rf"\.(?:{_SOURCE_SUFFIXES})$", token):
            return "rewrite", "package path (file not in this tree)"
        if (
            re.fullmatch(_IDENT, name)
            and rest[len(name) : len(name) + 1] in ("/", '"', "'", "`")
            and state.makes_up_package_paths()
        ):
            return "rewrite", "package path (file not in this tree)"
        return "ambiguous", f"{self.old}/{name} is not in the package: a path, or another prefix"

    def _decide_bare(
        self, state: _FileState, start: int, end: int, prev: str, before: str, after: str
    ) -> Decision:
        if state.is_local_name(start):
            return "keep", "local variable"
        if _IMPORT_STMT_RE.search(before) and not re.match(r"\s*[-/]", after):
            if _FROM_RE.search(before) and not re.match(r"\s+import\b", after):
                # ``"from <old>"`` with nothing else in the quotes is the start
                # of an import statement a guard tests for; with other words
                # around it ("a message from <old>") it is prose.
                opened = re.search(r"([\"'`])from\s+$", before)
                if opened is None or after[:1] != opened.group(1):
                    return "keep", "name"
            return "rewrite", "import"
        if _IMPORT_REGEX_RE.search(before):
            return "rewrite", "import"
        if _DASH_M_RE.search(before):
            return "rewrite", "module to run"
        if prev in ("'", '"') and after[:1] == prev:
            return self._decide_quoted(state, start, end, before)
        if _TOOL_DIR_RE.search(before) and re.match(r"(?:[\s\"'`,)\]]|$)", after):
            return "rewrite", "directory argument"
        if state.toml_section(start) in _PACKAGE_DATA_SECTIONS:
            if not before.strip() and re.match(r"\s*=", after):
                return "rewrite", "package data key"
        if state.imports_package() and state.is_python_code_token(start):
            # ``import <old>`` ... ``setattr(<old>, name, value)``.
            return "rewrite", "package object"
        return "keep", "name"

    def _decide_quoted(self, state: _FileState, start: int, end: int, before: str) -> Decision:
        """``"<old>"`` exactly: a path segment, an importable name, or a name."""
        if _IMPORTING_CALL_RE.search(before):
            return "rewrite", "importable name"
        if _DIRECTORY_LIST_RE.search(before):
            return "rewrite", "directory list"
        if state.looks_up_package_data(before):
            return "rewrite", "package data key"
        if _PREFIX_TEST_RE.search(before):
            return "ambiguous", "prefix test: on module names, or on something else"
        text = state.text
        # What stands left of the quote, across a line break.
        left = text[max(0, start - 200) : start - 1]
        if _DASH_M_LEFT_RE.search(left):
            return "rewrite", "module to run"
        follower = _FOLLOWER_RE.match(text, end + 1, end + 200)
        if follower and follower.group(1) == "," and not _JOIN_CALL_RE.search(before):
            follower = None  # a list of names, not the arguments of a path join
        if follower and self.resolves(follower.group(2)):
            return "rewrite", "path segment"
        joined = _JOIN_LEFT_RE.search(left)  # root / "<old>"
        if joined is None:
            return "keep", "name"
        by_comma = left.rstrip().endswith(",")
        if by_comma and not _JOIN_CALL_RE.search(state.line(start)):
            return "keep", "name"
        if joined.group(1) in ("'", '"') or _BIN_OPERAND_RE.search(left):
            # home / ".config" / "<old>", bin_dir / "<old>": a folder or a
            # command of that name somewhere else.
            return "keep", "file or folder of that name elsewhere"
        if by_comma and follower is None:
            return "ambiguous", "last argument of a path join: the package, or another folder"
        return "rewrite", "path segment"


def _stem(entry: str) -> str:
    return entry[:-3] if entry.endswith(".py") else entry


def _for_packages(globs: Iterable[str], old: str, new: str) -> list[str]:
    return [
        pattern.replace("{pkg}", package)
        for pattern in globs
        for package in ((old, new) if "{pkg}" in pattern else ("",))
    ]


class _FileState:
    """Lazy per-file facts the rules ask for."""

    def __init__(self, rewriter: Rewriter, path: str, text: str) -> None:
        self.rewriter = rewriter
        self.path = path
        self.text = text
        self.name = path.rsplit("/", 1)[-1]
        suffix = os.path.splitext(self.name)[1].lower()
        self.is_python = suffix in (".py", ".pyi", ".spec")
        self.is_web = suffix in _WEB_SUFFIXES
        self._legacy_spans: list[tuple[int, int, str]] | None = None
        self._assign_spans: list[tuple[int, int]] | None = None
        self._sections: list[tuple[int, str]] | None = None
        self._locals: frozenset[int] | None = None
        self._names: frozenset[tuple[int, int]] | None = None
        self._line_starts: list[int] | None = None
        self._made_up: bool | None = None
        self._imports: bool | None = None
        self._data_tables: frozenset[str] | None = None

    def line_span(self, index: int) -> tuple[int, int]:
        start = self.text.rfind("\n", 0, index) + 1
        end = self.text.find("\n", index)
        return start, len(self.text) if end == -1 else end

    def line(self, index: int) -> str:
        """The line around an offset, capped for single-line files."""
        start, end = self.line_span(index)
        return self.text[max(start, index - 400) : min(end, index + 400)]

    def position(self, index: int) -> tuple[int, int]:
        """1-based (line, column) of an offset."""
        if self._line_starts is None:
            self._line_starts = [0, *(m.end() for m in re.finditer("\n", self.text))]
        line = bisect.bisect_right(self._line_starts, index)
        return line, index - self._line_starts[line - 1] + 1

    def hit(self, index: int, reason: str) -> Hit:
        line, column = self.position(index)
        start, end = self.line_span(index)
        if end - start > 160:
            start, end = max(start, index - 70), min(end, index + 90)
        return Hit(self.path, line, column, reason, self.text[start:end].strip())

    def legacy_at(self, start: int, end: int) -> str:
        if self._legacy_spans is None:
            self._legacy_spans = sorted(
                (m.start(), m.end(), name)
                for pattern, name in self.rewriter._legacy
                for m in pattern.finditer(self.text)
            )
        spans = self._legacy_spans
        # Spans are short and begin at or just before the candidate.
        index = bisect.bisect_right(spans, (start, len(self.text), ""))
        for span_start, span_end, name in reversed(spans[max(0, index - 8) : index]):
            if span_start <= start and end <= span_end:
                return name
        return ""

    def in_legacy_assignment(self, index: int) -> bool:
        if self._assign_spans is None:
            self._assign_spans = [
                (m.start(), _statement_end(self.text, m.end()))
                for m in _LEGACY_ASSIGN_RE.finditer(self.text)
            ]
        return any(start <= index < end for start, end in self._assign_spans)

    def toml_section(self, index: int) -> str:
        if not self.name.endswith(".toml"):
            return ""
        if self._sections is None:
            self._sections = [
                (m.start(), m.group(1).strip()) for m in _TOML_SECTION_RE.finditer(self.text)
            ]
        current = ""
        for start, name in self._sections:
            if start > index:
                break
            current = name
        return current

    def has_module_path(self, line: str) -> bool:
        """True when ``line`` names a module at least two levels deep."""
        rewriter = self.rewriter
        # Either name: the answer must not change once the line is half rewritten.
        package = rf"(?:{re.escape(rewriter.old)}|{re.escape(rewriter.new)})"
        for match in re.finditer(rf"{package}\.({_IDENT})\.({_IDENT})", line):
            if f"{match.group(1)}.{match.group(2)}" in rewriter.submodules:
                return True
        return False

    def makes_up_package_paths(self) -> bool:
        """True when the file talks about files of the package that do not
        exist (a test that builds its own small tree): then every path below
        the name is one of them, and all of them are rewritten alike."""
        if self._made_up is None:
            rewriter = self.rewriter
            self._made_up = any(
                not rewriter.resolves(match.group(1) or match.group(2))
                for match in rewriter._made_up_path.finditer(self.text)
            )
        return self._made_up

    def _parse(self) -> ast.AST | None:
        try:
            return ast.parse(self.text.lstrip(""))
        except (SyntaxError, ValueError):
            return None

    def _local_lines(self) -> frozenset[int]:
        """Lines on which a LOCAL variable named like the package is read."""
        if self._locals is None:
            lines: set[int] = set()
            old = self.rewriter.old
            # Parsing every file costs more than the whole rest of a run; a
            # file can only bind the name where this cheap pattern matches.
            if self.is_python and self.rewriter._binding.search(self.text):
                tree = self._parse()
                bound = False
                loads: list[int] = []
                for node in ast.walk(tree) if tree is not None else ():
                    if isinstance(node, ast.Name) and node.id == old:
                        if isinstance(node.ctx, ast.Load):
                            loads.append(node.lineno)
                        else:
                            bound = True
                    elif isinstance(node, ast.arg) and node.arg == old:
                        bound = True
                    elif isinstance(node, ast.alias) and node.asname == old:
                        bound = True
                    elif isinstance(node, ast.ExceptHandler) and node.name == old:
                        bound = True
                    elif (
                        isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef)
                        and node.name == old
                    ):
                        bound = True
                if bound:
                    lines.update(loads)
            self._locals = frozenset(lines)
        return self._locals

    def is_local_name(self, index: int) -> bool:
        if not self.is_python:
            return False
        lines = self._local_lines()
        return bool(lines) and self.position(index)[0] in lines

    def is_python_code_token(self, index: int) -> bool:
        """True when the occurrence is a name in Python code, not text in a
        string or a comment."""
        if not self.is_python:
            return False
        if self._names is None:
            tree = self._parse()
            old = self.rewriter.old
            self._names = frozenset(
                (node.lineno, node.col_offset)
                for node in (ast.walk(tree) if tree is not None else ())
                if isinstance(node, ast.Name) and node.id == old
            )
        line, column = self.position(index)
        # The parser counts columns in UTF-8 bytes.
        offset = len(self.text[index - column + 1 : index].encode("utf-8"))
        return (line, offset) in self._names

    def looks_up_package_data(self, before: str) -> bool:
        """True when the quoted name after ``before`` is a key looked up in
        setuptools' package-data table, in one expression or through a
        variable this file assigned the table to."""
        if _PACKAGE_DATA_LOOKUP_RE.search(before):
            return True
        if self._data_tables is None:
            names = _PACKAGE_DATA_ASSIGN_RE.findall(self.text) if self.is_python else ()
            self._data_tables = frozenset(names)
        lookup = _LOOKUP_ON_NAME_RE.search(before)
        return lookup is not None and lookup.group(1) in self._data_tables

    def imports_package(self) -> bool:
        """True when the file binds the package's own name with an import."""
        if self._imports is None:
            pattern = (
                rf"^[ \t]*import[ \t]+(?:[\w.]+[ \t]*,[ \t]*)*{re.escape(self.rewriter.old)}\b"
            )
            self._imports = self.is_python and re.search(pattern, self.text, re.M) is not None
        return self._imports


# --------------------------------------------------------------------------- compatibility package


def stub_files(old: str, new: str) -> dict[str, str]:
    """The compatibility package, as ``{path: content}``.

    One module is enough: importing ``<old>`` hands back the ``<new>`` module
    itself and installs a finder that answers every ``<old>.x.y`` import with
    the ``<new>.x.y`` module object. ``python -m <old>.x.y`` works through the
    same finder (it serves the real module's code to ``runpy``), so no start
    command needs a file of its own.
    """
    init = f'''"""Compatibility alias: this package is now ``{new}``."""
# {STUB_MARKER}
# Do not edit and do not add modules here. Old start commands
# (``python -m {old}``, ``-m {old}.ui.web.launcher``, ...) and old imports keep
# working: every ``{old}.*`` name resolves to the SAME module object as its
# ``{new}.*`` twin, so no module is imported twice and no state exists twice.

from __future__ import annotations

import importlib
import importlib.abc
import importlib.machinery
import importlib.util
import os
import sys

# Read as text by updaters that predate the move; see the generator.
__version__ = "{STUB_VERSION}"

_OLD = "{old}"
_NEW = "{new}"


def _real_name(name: str) -> str:
    return _NEW + name[len(_OLD) :]


class _AliasFinder(importlib.abc.MetaPathFinder, importlib.abc.InspectLoader):
    """Answer ``{old}.x`` with the module object of ``{new}.x``."""

    def find_spec(self, fullname, path=None, target=None):  # noqa: ANN001, ANN201
        if not fullname.startswith(_OLD + "."):
            return None
        try:
            real = importlib.util.find_spec(_real_name(fullname))
        except (ImportError, ValueError):  # no parent package under the new name either
            return None
        if real is None:
            return None
        spec = importlib.machinery.ModuleSpec(
            fullname,
            self,
            origin=real.origin,
            is_package=real.submodule_search_locations is not None,
        )
        if real.submodule_search_locations is not None:
            spec.submodule_search_locations = list(real.submodule_search_locations)
        spec.has_location = real.has_location
        spec.cached = real.cached
        return spec

    def create_module(self, spec):  # noqa: ANN001, ANN201
        module = importlib.import_module(_real_name(spec.name))
        # The import system stamps the alias spec on whatever this returns;
        # ``exec_module`` puts the module's own spec back.
        spec.loader_state = getattr(module, "__spec__", None)
        return module

    def exec_module(self, module) -> None:  # noqa: ANN001
        # Already executed under its real name. It keeps its real spec, so a
        # reload, its resources and its relative imports behave as if the old
        # name had never been used.
        alias = getattr(module, "__spec__", None)
        real = getattr(alias, "loader_state", None)
        if real is not None and getattr(alias, "loader", None) is self:
            module.__spec__ = real

    # ``python -m {old}.x`` asks the loader for code, not for a module.
    def _real_loader(self, fullname: str):  # noqa: ANN202
        spec = importlib.util.find_spec(_real_name(fullname))
        if spec is None or spec.loader is None:
            raise ImportError(f"no module named {{fullname}}", name=fullname)
        return spec.loader

    def get_code(self, fullname):  # noqa: ANN001, ANN201
        return self._real_loader(fullname).get_code(_real_name(fullname))

    def get_source(self, fullname):  # noqa: ANN001, ANN201
        return self._real_loader(fullname).get_source(_real_name(fullname))

    def is_package(self, fullname):  # noqa: ANN001, ANN201
        return self._real_loader(fullname).is_package(_real_name(fullname))


def _install() -> None:
    if not any(isinstance(finder, _AliasFinder) for finder in sys.meta_path):
        # First, so the path finder never builds a second copy from the real
        # package's directory under the old name.
        sys.meta_path.insert(0, _AliasFinder())
    try:
        real = importlib.import_module(_NEW)
    except ModuleNotFoundError as exc:
        if exc.name != _NEW:
            raise
        # An editable install made before the move maps only the old name to
        # its directory; the package itself sits next to this one.
        sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
        importlib.invalidate_caches()
        real = importlib.import_module(_NEW)
    prefix = _NEW + "."
    for name, module in list(sys.modules.items()):
        if name.startswith(prefix):
            sys.modules.setdefault(_OLD + name[len(_NEW) :], module)
    sys.modules[_OLD] = real


_install()
'''
    return {f"{old}/__init__.py": init}


# --------------------------------------------------------------------------- the run


@dataclass
class Report:
    moves: list[tuple[str, str]] = field(default_factory=list)
    rewritten: dict[str, Counter[str]] = field(default_factory=dict)
    ambiguous: list[Hit] = field(default_factory=list)
    explained: list[Hit] = field(default_factory=list)
    stubs: list[str] = field(default_factory=list)
    blocked: list[str] = field(default_factory=list)

    @property
    def pending(self) -> bool:
        """True when a run would still change something."""
        return bool(self.moves or self.rewritten or self.stubs)

    def totals(self) -> Counter[str]:
        totals: Counter[str] = Counter()
        for rules in self.rewritten.values():
            totals.update(rules)
        return totals

    def as_json(self) -> dict[str, object]:
        totals = self.totals()
        return {
            "files_moved": len(self.moves),
            "files_rewritten": len(self.rewritten),
            "references_rewritten": sum(totals.values()),
            "references_by_rule": dict(sorted(totals.items())),
            "compatibility_files": self.stubs,
            "ambiguous": [vars(hit) for hit in self.ambiguous],
            "blocked": self.blocked,
            "rewritten": {path: dict(rules) for path, rules in sorted(self.rewritten.items())},
        }


def _read(path: Path) -> bytes | None:
    try:
        return path.read_bytes()
    except OSError:
        return None


def plan(
    root: Path, old: str, new: str, explain: Iterable[str] = ()
) -> tuple[Report, dict[str, bytes]]:
    """Work out everything a run would do, without touching the checkout.

    Returns the report and ``{path after the move: new content}`` for the
    files whose content changes.
    """
    rewriter = Rewriter.from_tree(root, old, new)
    rewriter.explain = frozenset(explain)
    report = Report()
    contents: dict[str, bytes] = {}
    files = tracked_files(root)
    tracked = {path for path, _mode in files}
    for path, mode in files:
        if mode not in ("100644", "100755"):
            continue  # a symlink or a submodule: no text to rewrite, and it stays
        data = _read(root / path)
        if data is None:
            continue  # deleted in the working tree
        target = path
        if path.startswith(old + "/") and STUB_MARKER.encode() not in data[:400]:
            target = rewriter.map_path(path)
            if target in tracked or (root / target).exists():
                report.blocked.append(f"{path} -> {target}: the target already exists")
                continue
            report.moves.append((path, target))
        new_data, result = rewriter.rewrite(path, data)
        report.ambiguous.extend(result.ambiguous)
        report.explained.extend(result.explained)
        if result.changed and new_data != data:
            report.rewritten[target] = result.rewrites
            contents[target] = new_data
    # The compatibility package appears once the real one has left (or is
    # leaving) the old directory; a tree that never had the package gets none.
    if report.moves or any(path.startswith(new + "/") for path in tracked):
        leaving = {source for source, _target in report.moves}
        for path, content in stub_files(old, new).items():
            current = None if path in leaving else _read(root / path)
            if current is None or current.replace(b"\r\n", b"\n") != content.encode("utf-8"):
                report.stubs.append(path)
    return report, contents


def _move(root: Path, old: str, new: str, moves: list[tuple[str, str]]) -> None:
    """Move the tracked files with as few ``git mv`` calls as the checkout
    allows: a whole directory wherever its target is still free (untracked
    caches and ``node_modules`` ride along), its children one by one where a
    leftover directory is already in the way."""
    if not moves:
        return
    leaving = {source for source, _target in moves}
    staying = {
        path
        for path, _mode in tracked_files(root)
        if path.startswith(old + "/") and path not in leaving
    }

    def move(source: str, target: str) -> None:
        below = source + "/"
        is_file = source in leaving
        whole = is_file or not any(path.startswith(below) for path in staying)
        if whole and not (root / target).exists():
            (root / target).parent.mkdir(parents=True, exist_ok=True)
            proc = _git(root, "mv", "--", source, target)
            if proc.returncode == 0:
                return
            reason = proc.stderr.decode("utf-8", "replace").strip()
            if is_file:
                raise SystemExit(f"git mv {source} {target} failed: {reason}")
            print(f"[rename] {source}/ did not move in one step ({reason}); going deeper")
        elif is_file:
            raise SystemExit(f"cannot move {source}: {target} already exists")
        children = sorted(
            {path[len(below) :].split("/", 1)[0] for path in leaving if path.startswith(below)}
        )
        for child in children:
            if (root / source / child).exists():  # a failed rename may have got this far
                move(f"{source}/{child}", f"{target}/{child}")

    move(old, new)


def apply(root: Path, old: str, new: str, *, stage: bool = True) -> Report:
    """Run the codemod on the checkout at ``root``."""
    report, contents = plan(root, old, new)
    if report.blocked:
        return report
    _move(root, old, new, report.moves)
    for path, data in contents.items():
        (root / path).write_bytes(data)
    stubs = stub_files(old, new)
    for path in report.stubs:
        target = root / path
        target.parent.mkdir(parents=True, exist_ok=True)
        target.write_bytes(stubs[path].encode("utf-8"))
    touched = sorted({*contents, *report.stubs})
    if stage and touched:
        # Exactly the paths this run wrote: the checkout may hold other work.
        # --force because tracked files do live below ignored directories.
        proc = _git(
            root,
            "add",
            "--force",
            "--pathspec-from-file=-",
            "--pathspec-file-nul",
            stdin="\0".join(touched).encode("utf-8"),
        )
        if proc.returncode != 0:
            raise SystemExit(f"git add failed: {proc.stderr.decode('utf-8', 'replace')}")
    return report


def _print_report(report: Report, *, verbose: bool, limit: int) -> None:
    if verbose:
        for source, target in report.moves[:limit]:
            print(f"move     {source} -> {target}")
        if len(report.moves) > limit:
            print(f"move     ... and {len(report.moves) - limit} more")
        for path, rules in sorted(report.rewritten.items()):
            detail = ", ".join(f"{rule} x{count}" for rule, count in sorted(rules.items()))
            print(f"rewrite  {path}: {detail}")
        for path in report.stubs:
            print(f"write    {path} (compatibility package)")
    for hit in report.explained:
        print("explain  " + hit.render())
    if report.ambiguous:
        print(f"\nAMBIGUOUS - not touched, a person decides ({len(report.ambiguous)}):")
        for hit in report.ambiguous:
            print("  " + hit.render())
    for line in report.blocked:
        print(f"BLOCKED  {line}")
    totals = report.totals()
    print(
        f"\n{len(report.moves)} file(s) to move, {len(report.rewritten)} file(s) to rewrite "
        f"({sum(totals.values())} reference(s)), {len(report.stubs)} compatibility file(s), "
        f"{len(report.ambiguous)} ambiguous hit(s)."
    )
    for rule, count in sorted(totals.items()):
        print(f"  {count:>6}  {rule}")


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    parser.add_argument("--from", dest="old", required=True, help="Current package directory.")
    parser.add_argument("--to", dest="new", required=True, help="New package directory.")
    parser.add_argument("--root", type=Path, default=None, help="Checkout (default: here).")
    mode = parser.add_mutually_exclusive_group()
    mode.add_argument("--dry-run", action="store_true", help="Report only; change nothing.")
    mode.add_argument(
        "--check", action="store_true", help="Exit 1 when a run would still change something."
    )
    parser.add_argument("--no-stage", action="store_true", help="Leave the rewrites unstaged.")
    parser.add_argument("--quiet", action="store_true", help="Totals and ambiguous hits only.")
    parser.add_argument("--json", type=Path, help="Also write the full report to this file.")
    parser.add_argument("--limit", type=int, default=20, help="Moves to list (default 20).")
    parser.add_argument(
        "--explain",
        action="append",
        default=[],
        metavar="RULE",
        help="List every decision made by this rule ('*' for all); repeatable.",
    )
    args = parser.parse_args(argv)
    for stream in (sys.stdout, sys.stderr):
        if hasattr(stream, "reconfigure"):
            stream.reconfigure(encoding="utf-8", errors="replace")
    top = _git((args.root or Path.cwd()).resolve(), "rev-parse", "--show-toplevel")
    if top.returncode != 0:
        print(f"not a git checkout: {args.root or Path.cwd()}", file=sys.stderr)
        return 2
    root = Path(top.stdout.decode("utf-8").strip())

    if args.dry_run or args.check or args.explain:
        report, _contents = plan(root, args.old, args.new, args.explain)
    else:
        report = apply(root, args.old, args.new, stage=not args.no_stage)
    if args.json:
        args.json.write_text(json.dumps(report.as_json(), indent=2), encoding="utf-8")
    _print_report(report, verbose=not (args.quiet or args.check), limit=args.limit)
    if report.blocked:
        return 2
    if args.check and report.pending:
        print(f"check failed: the tree still refers to the {args.old}/ layout:")
        for source, _target in report.moves[:20]:
            print(f"  {source} (not moved)")
        for path in sorted(report.rewritten)[:40]:
            print(f"  {path}")
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main())