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.

build(rename): add the package rename codemod and wire it into branch integration (#592)

Ruben Lütkece5310bedd64
diff --git a/docs/ci-pipeline.md b/docs/ci-pipeline.md
index 21c500a9b5..eceac20d49 100644
--- a/docs/ci-pipeline.md
+++ b/docs/ci-pipeline.md
@@ -280,6 +280,30 @@ static gates, runs the tests the diff can reach, pushes, and asks GitHub to
queue the pull request once it is green. It refuses a dirty worktree and
never stashes or force-pushes.
+### A branch from before a package move
+
+Moving the Python package directory is one commit whose content is exactly
+the output of `scripts/rename/rewrite_package.py` (`--dry-run` lists what a
+run would do and the hits it cannot decide, `--check` fails while the tree
+still refers to the old layout). A branch cut before that commit is never
+merged across it by hand. Both `agent_land.py` and the merge train bring the
+branch to the last commit of the old layout first, an ordinary update, and
+then replay the move: the script, loaded from the move commit itself, is
+applied to the files the branch changed, every other file is taken from the
+move commit, and the result is committed as a merge of the two. Nothing can
+conflict in that step. The train does it in two ticks, one per step; locally
+it is one run, and from the move onwards the branch is updated by merge, not
+by rebase. Until main carries the new directory none of this runs.
+
+`agent_land.py` runs the branch's own copy of these scripts. A branch cut
+before they could replay a move stops at the move with an ordinary conflict
+report and changes nothing: rebase it onto the last commit of the old layout
+by hand, which brings the scripts along, and run `agent_land.py` again. The
+merge train always runs main's copy and needs no such step.
+
+`classify_changes.py` reads a changed path under either name of the package
+directory as the same path, so the move turns no lane off.
+
## 3. Releases, installers and updates
A release happens **only** when the maintainer asks for one.
diff --git a/scripts/agent_land.py b/scripts/agent_land.py
index c427ca6b0d..486173ffa8 100644
--- a/scripts/agent_land.py
+++ b/scripts/agent_land.py
@@ -141,9 +141,13 @@ def main(argv: list[str] | None = None) -> int:
print("\nThese files conflict and need a human-quality resolution:")
for path in report.get("unresolved", []): # type: ignore[union-attr]
print(f" - {path}")
+ # A branch that predates the package move stops at the commit before
+ # it; one already carried across the move holds a merge a rebase drops.
+ target = report.get("onto", upstream)
+ verb = "merge" if report.get("package_move") else "rebase"
print(
- f"\nRun `git rebase {upstream}`, resolve them (keep both sides' intent), "
- "`git add` them, `git rebase --continue`, then run this script again."
+ f"\nRun `git {verb} {target}`, resolve them (keep both sides' intent), "
+ f"`git add` them, `git {verb} --continue`, then run this script again."
)
return 3
diff --git a/scripts/ci/agent_integrate.py b/scripts/ci/agent_integrate.py
index 723f8cff80..aae6c937c8 100644
--- a/scripts/ci/agent_integrate.py
+++ b/scripts/ci/agent_integrate.py
@@ -27,6 +27,10 @@ Conflicts are resolved by file class, cheapest first:
``git rerere`` is on throughout, so a resolution recorded once is replayed.
+A branch cut before the package directory was moved is not merged across that
+commit at all: it is updated to the commit before it, then the rename script
+is replayed on the branch's own changes (``replay_package_move``).
+
Usage::
agent_integrate.py update --onto origin/main [--mode merge|rebase]
@@ -39,6 +43,7 @@ from __future__ import annotations
import argparse
import fnmatch
+import importlib.util
import json
import os
import py_compile
@@ -53,6 +58,7 @@ from dataclasses import dataclass, field
from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parents[2]
+_NO_WINDOW = getattr(subprocess, "CREATE_NO_WINDOW", 0) if os.name == "nt" else 0
FRONTEND = "jarvis/ui/web/frontend"
# (glob, regenerator key). Main's copy is taken, then the key regenerates it.
@@ -77,6 +83,13 @@ UNION: tuple[str, ...] = (
".gitignore",
"docs/BUGS.md",
)
+# The package directory before and after its rename, and the script whose
+# output IS the commit that renames it. Until main carries the new directory
+# nothing here does anything; afterwards a branch that still has the old one
+# is carried across by ``replay_package_move`` instead of by conflicts.
+OLD_PACKAGE = "jarvis"
+NEW_PACKAGE = "dodaios"
+RENAME_SCRIPT = "scripts/rename/rewrite_package.py"
AGENT_BRANCH_PREFIXES = ("codex/", "claude/", "agent/", "agents/", "gemini/", "cursor/", "bot/")
OPT_OUT_LABELS = {"no-auto-merge", "do-not-merge", "wip", "needs-human"}
OPT_IN_LABEL = "auto-merge"
@@ -332,6 +345,139 @@ def _in_progress(cwd: Path) -> str | None:
return None
+def _in_tree(rev: str, path: str, cwd: Path) -> bool:
+ return git("cat-file", "-e", f"{rev}:{path}", check=False, cwd=cwd).returncode == 0
+
+
+def _move_commit(onto: str, cwd: Path) -> str:
+ """The commit on ``onto``'s first-parent line that added the new directory."""
+ found = git(
+ "log", "-1", "--first-parent", "-m", "--diff-filter=A", "--format=%H", onto,
+ "--", f"{NEW_PACKAGE}/__init__.py",
+ check=False, cwd=cwd,
+ ) # fmt: skip
+ return found.stdout.strip()
+
+
+def carried_package_move(onto: str, cwd: Path = REPO_ROOT) -> str | None:
+ """The move commit when HEAD was carried across the package move by an
+ earlier update: it has the new layout and still holds commits of its own
+ from the old one, below the merge that replayed the move. A rebase would
+ drop that merge and replay those commits onto the new layout, a conflict
+ in every file they touch, so such a branch is updated by merge from then
+ on. ``None`` in every other case - which is every case until main has the
+ new directory."""
+ new_init = f"{NEW_PACKAGE}/__init__.py"
+ if not _in_tree(onto, new_init, cwd) or not _in_tree("HEAD", new_init, cwd):
+ return None
+ own = git("rev-list", "--no-merges", "--topo-order", f"{onto}..HEAD", check=False, cwd=cwd)
+ # Oldest first: a commit from before the move is the first one asked.
+ if all(_in_tree(commit, new_init, cwd) for commit in reversed(own.stdout.split())):
+ return None
+ return _move_commit(onto, cwd) or None
+
+
+def package_move(onto: str, cwd: Path = REPO_ROOT) -> tuple[str, str] | None:
+ """``(last commit before the move, the move commit)`` when ``onto`` has
+ renamed the package directory and HEAD has not; ``None`` in every other
+ case - which is every case until that rename lands on main."""
+ new_init = f"{NEW_PACKAGE}/__init__.py"
+ if not _in_tree(onto, new_init, cwd) or _in_tree("HEAD", new_init, cwd):
+ return None
+ if not _in_tree("HEAD", f"{OLD_PACKAGE}/__init__.py", cwd):
+ return None
+ move = _move_commit(onto, cwd)
+ if not move or not _in_tree(move, RENAME_SCRIPT, cwd):
+ return None # renamed by hand: nothing to replay, the ordinary update applies
+ parent = git("rev-parse", "--verify", "--quiet", f"{move}^", check=False, cwd=cwd)
+ before = parent.stdout.strip()
+ if not before or _in_tree(before, new_init, cwd):
+ return None
+ return before, move
+
+
+def _git_bytes(
+ *args: str, cwd: Path, stdin: bytes | None = None, env: dict[str, str] | None = None
+) -> bytes:
+ return subprocess.run( # noqa: S603
+ ["git", *args], # noqa: S607
+ cwd=cwd,
+ input=stdin,
+ env=env,
+ capture_output=True,
+ check=True,
+ creationflags=_NO_WINDOW,
+ ).stdout
+
+
+def _load_rename_script(move: str, cwd: Path): # noqa: ANN202
+ """The rename script exactly as the move commit ran it. It is main's code
+ and treats the branch's files as text; it never executes them."""
+ source = _git_bytes("show", f"{move}:{RENAME_SCRIPT}", cwd=cwd)
+ with tempfile.TemporaryDirectory(prefix="package-rename-") as tmp:
+ path = Path(tmp) / "package_rename_at_move.py"
+ path.write_bytes(source)
+ spec = importlib.util.spec_from_file_location(path.stem, path)
+ if spec is None or spec.loader is None:
+ raise OSError(f"cannot load {RENAME_SCRIPT} from {move}")
+ module = importlib.util.module_from_spec(spec)
+ sys.modules[spec.name] = module # dataclasses look their module up by name
+ try:
+ spec.loader.exec_module(module)
+ finally:
+ sys.modules.pop(spec.name, None)
+ return module
+
+
+def replay_package_move(before: str, move: str, cwd: Path = REPO_ROOT) -> str:
+ """Carry HEAD across the package rename; returns the new commit.
+
+ HEAD must contain ``before``. The move commit is the rename script's
+ output on ``before``, so the same script applied to the files THIS branch
+ changed is the branch's side of the merge, and every other file is the
+ move commit's own. That tree is committed as the merge of HEAD with the
+ move commit: no file is merged by hand and none can conflict.
+ """
+ rewriter = _load_rename_script(move, cwd).Rewriter.from_tree(cwd, OLD_PACKAGE, NEW_PACKAGE)
+ listing = _git_bytes("ls-tree", "-r", "-z", "HEAD", cwd=cwd).decode("utf-8", "surrogateescape")
+ entries: dict[str, tuple[str, str]] = {}
+ for record in listing.split("\0"):
+ if record:
+ meta, _, path = record.partition("\t")
+ mode, _kind, sha = meta.split(" ")
+ entries[path] = (mode, sha)
+ changed = _git_bytes("diff", "--name-only", "--no-renames", "-z", before, "HEAD", cwd=cwd)
+ index_info: list[str] = []
+ for path in changed.decode("utf-8", "surrogateescape").split("\0"):
+ if not path:
+ continue
+ target = rewriter.map_path(path)
+ if path not in entries: # the branch deleted it
+ index_info.append(f"0 {'0' * 40}\t{target}")
+ continue
+ mode, sha = entries[path]
+ if mode in ("100644", "100755"):
+ data = _git_bytes("cat-file", "blob", sha, cwd=cwd)
+ rewritten = rewriter.transform(path, data)
+ if rewritten != data:
+ sha = _git_bytes(
+ "hash-object", "-w", "--stdin", cwd=cwd, stdin=rewritten
+ ).decode().strip() # fmt: skip
+ index_info.append(f"{mode} {sha}\t{target}")
+ with tempfile.TemporaryDirectory(prefix="package-rename-") as tmp:
+ env = {**os.environ, "GIT_INDEX_FILE": str(Path(tmp) / "index")}
+ _git_bytes("read-tree", move, cwd=cwd, env=env)
+ _git_bytes(
+ "update-index", "-z", "--index-info", cwd=cwd, env=env,
+ stdin="".join(f"{line}\0" for line in index_info).encode("utf-8", "surrogateescape"),
+ ) # fmt: skip
+ tree = _git_bytes("write-tree", cwd=cwd, env=env).decode().strip()
+ message = f"Merge the {OLD_PACKAGE} -> {NEW_PACKAGE} package move"
+ commit = git("commit-tree", tree, "-p", "HEAD", "-p", move, "-m", message, cwd=cwd).stdout
+ git("merge", "--ff-only", commit.strip(), cwd=cwd)
+ return commit.strip()
+
+
def update(onto: str, mode: str, resolver_cmd: str, cwd: Path = REPO_ROOT) -> dict[str, object]:
"""Update HEAD with ``onto``. Returns a JSON-able report; ``status`` is
``up-to-date`` | ``updated`` | ``conflict``."""
@@ -341,6 +487,24 @@ def update(onto: str, mode: str, resolver_cmd: str, cwd: Path = REPO_ROOT) -> di
regen: set[str] = set()
resolved: list[str] = []
ai: list[str] = []
+ moved = package_move(onto, cwd)
+ carried = ""
+ if moved:
+ before, move = moved
+ # Everything up to the move is an ordinary update between two trees of
+ # the same layout; the move itself is replayed, never merged.
+ first = update(before, mode, resolver_cmd, cwd)
+ if first["status"] == "conflict":
+ return {**first, "onto": before}
+ resolved += first.get("resolved", []) # type: ignore[arg-type]
+ ai += first.get("ai_resolved", []) # type: ignore[arg-type]
+ replay_package_move(before, move, cwd)
+ carried = move
+ elif mode == "rebase":
+ carried = carried_package_move(onto, cwd) or ""
+ if carried:
+ report["package_move"] = carried
+ mode = "merge" # a rebase would drop the merge that carries the move
if mode == "merge":
result = git("merge", "--no-edit", "--no-ff", onto, check=False, cwd=cwd)
if result.returncode != 0:
@@ -349,8 +513,11 @@ def update(onto: str, mode: str, resolver_cmd: str, cwd: Path = REPO_ROOT) -> di
ai += res.ai_resolved
regen |= res.regenerate
if res.unresolved or conflicted_files(cwd):
+ left = res.unresolved or conflicted_files(cwd)
git("merge", "--abort", check=False, cwd=cwd)
- return {"status": "conflict", "unresolved": res.unresolved or conflicted_files(cwd)}
+ # A replayed move stays: the branch is whole in the new layout.
+ across = {"package_move": carried} if carried else {}
+ return {"status": "conflict", "unresolved": left, **across}
git("commit", "--no-edit", check=False, cwd=cwd)
else:
git("rebase", onto, check=False, cwd=cwd)
@@ -792,6 +959,16 @@ def merge_main_into(
if git("merge-base", "--is-ancestor", main_sha, "HEAD", check=False, cwd=wt).returncode == 0:
return {"status": "up-to-date"}
state: dict[str, object] = {"status": "merged", "resolved": [], "ai_resolved": [], "regen": []}
+ moved = package_move(main_sha, wt)
+ if moved:
+ before, move = moved
+ if git("merge-base", "--is-ancestor", before, "HEAD", check=False, cwd=wt).returncode == 0:
+ replay_package_move(before, move, wt)
+ else:
+ # This tick brings the branch to the last commit of the old
+ # layout; the next one replays the move on top of that.
+ main_sha = before
+ state["onto"] = before
message = f"Merge main into {branch}"
result = git("merge", "--no-edit", "--no-ff", "-m", message, main_sha, check=False, cwd=wt)
if result.returncode != 0:
@@ -993,7 +1170,12 @@ def apply_update(
or git("rev-parse", ref, check=False, cwd=checkout).stdout.strip() != sha
):
return "update bundle missing or unreadable; next tick"
- if not _bundle_is_safe(sha, entry, data["main"], checkout):
+ # A branch that predates the package move is first brought to the last
+ # commit before it - a commit of main's own history, never one the
+ # integrate job could make up.
+ onto = str(state.get("onto") or data["main"])
+ known = git("merge-base", "--is-ancestor", onto, data["main"], check=False, cwd=checkout)
+ if known.returncode != 0 or not _bundle_is_safe(sha, entry, onto, checkout):
return "update bundle rejected (not the planned head plus main); next tick"
push = git("push", "origin", f"{sha}:refs/heads/{branch}", check=False, cwd=checkout)
if push.returncode != 0:
diff --git a/scripts/ci/classify_changes.py b/scripts/ci/classify_changes.py
index 706613a0ef..60903dcf20 100644
--- a/scripts/ci/classify_changes.py
+++ b/scripts/ci/classify_changes.py
@@ -66,6 +66,13 @@ _PY_IRRELEVANT_FILES = {
_PIPELINE_PREFIXES = (".github/workflows/", ".github/actions/", "scripts/ci/")
+# The package directory as every table below spells it. A changed path under
+# any name the directory has had is read as this spelling first, so renaming
+# the directory can never turn a lane off: neither for the commit that moves
+# it nor for a branch that still carries the other layout.
+_PACKAGE_PREFIX = "jarvis/"
+_PACKAGE_NAMES = ("jarvis", "dodaios")
+
_FRONTEND_PREFIXES = ("jarvis/ui/web/frontend/",)
_FRONTEND_FILES = {"scripts/ci/check_frontend_bundle_budget.py"}
@@ -252,6 +259,9 @@ def _normalize(paths: Iterable[str]) -> list[str]:
path = raw.strip().replace("\\", "/")
if path.startswith("./"):
path = path[2:]
+ head, slash, rest = path.partition("/")
+ if slash and head in _PACKAGE_NAMES:
+ path = _PACKAGE_PREFIX + rest
if path:
out.append(path)
return out
diff --git a/scripts/rename/rewrite_package.py b/scripts/rename/rewrite_package.py
new file mode 100644
index 0000000000..a2d332ec51
--- /dev/null
+++ b/scripts/rename/rewrite_package.py
@@ -0,0 +1,1396 @@
+#!/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.",
+ r"entry[-_]points?\W{{0,3}}[\"']{old}\.[a-z_<>*]+[\"']"
+ r"|\bgroup\s*=\s*[\"']{old}\.[a-z_]+[\"']"
+ r"|entry_points(?:_for)?\(\s*[\"']{old}\.[a-z_]+[\"']",
+ (
+ '[project.entry-points."jarvis.brain"]',
+ '[project.entry-points."jarvis.<group>"]',
+ 'entry_points(group="jarvis.tool")',
+ 'entry_points_for("jarvis.stt")',
+ ),
+ ),
+ 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("docs/BUGS.md", "the bug register cites paths as they were when a bug was found"),
+ 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("**/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
+
+
+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"),
+)
+
+#: 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 = _for_packages((kept.glob for kept in UNRESOLVED_PATHS_KEPT), 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) -> bool:
+ return any(fnmatch.fnmatchcase(path, pattern) for pattern 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):
+ 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())
diff --git a/tests/unit/ci/test_package_move_integration.py b/tests/unit/ci/test_package_move_integration.py
new file mode 100644
index 0000000000..3aa86817e1
--- /dev/null
+++ b/tests/unit/ci/test_package_move_integration.py
@@ -0,0 +1,468 @@
+"""A branch that predates the package move is carried across it by replaying
+the rename script, and CI lanes read both names of the package directory.
+
+The old package name appears all over this file on purpose; the codemod never
+rewrites it (``FROZEN_FILES``).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from scripts.ci import agent_integrate, classify_changes
+from scripts.rename import rewrite_package as codemod
+
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+_NO_WINDOW = getattr(subprocess, "CREATE_NO_WINDOW", 0)
+
+_BASE = {
+ "jarvis/__init__.py": '__version__ = "1.0.0"\n',
+ "jarvis/core/__init__.py": "",
+ "jarvis/core/alpha.py": "from jarvis.core import beta\n\nVALUE = 1\n",
+ "jarvis/core/beta.py": "NAME = 'beta'\n",
+ "jarvis/core/gamma.py": "from jarvis.core.beta import NAME\n",
+ "tests/test_alpha.py": "from jarvis.core.alpha import VALUE\n",
+ "docs/guide.md": "Read `jarvis/core/alpha.py`.\n",
+ "CHANGELOG.md": "# Changelog\n\n- base\n",
+ "app.py": "VALUE = 1\n",
+}
+
+
+def _git(repo: Path, *args: str) -> str:
+ return subprocess.run(
+ ["git", "-C", str(repo), *args],
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ check=True,
+ creationflags=_NO_WINDOW,
+ ).stdout
+
+
+def _write(repo: Path, files: dict[str, str]) -> None:
+ for name, text in files.items():
+ path = repo / name
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(text, encoding="utf-8", newline="")
+
+
+def _commit(repo: Path, message: str, files: dict[str, str] | None = None) -> str:
+ _write(repo, files or {})
+ _git(repo, "add", "-A", ".")
+ _git(repo, "commit", "-q", "-m", message)
+ return _git(repo, "rev-parse", "HEAD").strip()
+
+
+def repo(tmp_path):
+ """main with the old layout and the rename script, and a ``feature``
+ branch cut from it. HEAD is main."""
+ root = tmp_path / "repo"
+ root.mkdir()
+ _git(root, "init", "-q", "-b", "main")
+ _git(root, "config", "user.email", "[email protected]")
+ _git(root, "config", "user.name", "t")
+ _git(root, "config", "core.autocrlf", "false")
+ script = root / agent_integrate.RENAME_SCRIPT
+ script.parent.mkdir(parents=True)
+ shutil.copyfile(_REPO_ROOT / agent_integrate.RENAME_SCRIPT, script)
+ _commit(root, "base", _BASE)
+ _git(root, "branch", "feature")
+ return root
+
+
+def _move_on_main(repo: Path) -> str:
+ """The move commit: exactly the rename script's output."""
+ _git(repo, "checkout", "-q", "main")
+ report = codemod.apply(repo, agent_integrate.OLD_PACKAGE, agent_integrate.NEW_PACKAGE)
+ assert report.moves and not report.blocked
+ _git(repo, "commit", "-q", "-m", "refactor: move the package")
+ return _git(repo, "rev-parse", "HEAD").strip()
+
+
+def _feature_work(repo: Path) -> None:
+ _git(repo, "checkout", "-q", "feature")
+ _commit(
+ repo,
+ "feature work",
+ {
+ # An import line the move rewrites too: a plain merge would conflict here.
+ "jarvis/core/alpha.py": "from jarvis.core import beta, gamma\n\nVALUE = 2\n",
+ "jarvis/core/delta.py": "from jarvis.core.alpha import VALUE\n",
+ "docs/guide.md": "Read `jarvis/core/alpha.py` and `jarvis/core/delta.py`.\n",
+ },
+ )
+ (repo / "jarvis/core/gamma.py").unlink()
+ _commit(repo, "feature: drop gamma")
+
+
+def _show(repo: Path, name: str) -> str:
+ return _git(repo, "show", f"HEAD:{name}")
+
+
+def _tree(repo: Path, rev: str = "HEAD") -> set[str]:
+ return set(_git(repo, "ls-tree", "-r", "--name-only", rev).split())
+
+
+# --------------------------------------------------------------------------- no move yet
+
+
+def test_nothing_happens_while_main_still_has_the_old_layout(repo):
+ _commit(repo, "main work", {"app.py": "VALUE = 2\n"})
+ _feature_work(repo)
+
+ assert agent_integrate.package_move("main", repo) is None
+ assert agent_integrate.carried_package_move("main", repo) is None
+ report = agent_integrate.update("main", "rebase", "", repo)
+
+ assert report["status"] == "updated" and "package_move" not in report
+ assert "jarvis/core/delta.py" in _tree(repo) and not (repo / "dodaios").exists()
+ # A plain rebase: no merge commit was made.
+ assert _git(repo, "rev-list", "--merges", "main..HEAD").strip() == ""
+
+
+def test_a_branch_that_already_moved_is_updated_the_ordinary_way(repo):
+ move = _move_on_main(repo)
+ _git(repo, "checkout", "-q", "-b", "later")
+ _commit(repo, "later work", {"dodaios/core/beta.py": "NAME = 'later'\n"})
+ _git(repo, "checkout", "-q", "main")
+ _commit(repo, "main work", {"app.py": "VALUE = 2\n"})
+ _git(repo, "checkout", "-q", "later")
+
+ assert agent_integrate.package_move("main", repo) is None
+ assert agent_integrate.carried_package_move("main", repo) is None
+ report = agent_integrate.update("main", "rebase", "", repo)
+ assert report["status"] == "updated" and "package_move" not in report
+ assert _git(repo, "merge-base", "--is-ancestor", move, "HEAD") == ""
+ # Still a plain rebase: a branch born in the new layout carries no merge.
+ assert _git(repo, "rev-list", "--merges", "main..HEAD").strip() == ""
+
+
+def test_a_move_made_by_hand_is_not_replayed(repo):
+ _git(repo, "rm", "-q", agent_integrate.RENAME_SCRIPT)
+ _git(repo, "mv", "jarvis", "dodaios")
+ _git(repo, "commit", "-q", "-m", "move by hand")
+ _git(repo, "checkout", "-q", "feature")
+
+ assert agent_integrate.package_move("main", repo) is None
+
+
+# --------------------------------------------------------------------------- the replay
+
+
[email protected]("mode", ["merge", "rebase"])
+def test_a_branch_from_before_the_move_is_carried_across_without_conflicts(repo, mode):
+ _commit(repo, "main work before the move", {"app.py": "VALUE = 2\n"})
+ move = _move_on_main(repo)
+ after = _commit(repo, "main work after the move", {"dodaios/core/beta.py": "NAME = 'new'\n"})
+ _feature_work(repo)
+
+ assert agent_integrate.package_move("main", repo) == (
+ _git(repo, "rev-parse", f"{move}^").strip(),
+ move,
+ )
+ report = agent_integrate.update("main", mode, "", repo)
+
+ assert report["status"] == "updated", report
+ assert report["package_move"] == move
+ assert _git(repo, "status", "--porcelain").strip() == ""
+ assert _git(repo, "merge-base", "--is-ancestor", after, "HEAD") == ""
+ tree = _tree(repo)
+ # The branch's own changes arrived in the new layout, rewritten ...
+ assert _show(repo, "dodaios/core/alpha.py") == (
+ "from dodaios.core import beta, gamma\n\nVALUE = 2\n"
+ )
+ assert _show(repo, "dodaios/core/delta.py") == "from dodaios.core.alpha import VALUE\n"
+ assert _show(repo, "docs/guide.md") == (
+ "Read `dodaios/core/alpha.py` and `dodaios/core/delta.py`.\n"
+ )
+ assert "dodaios/core/gamma.py" not in tree # ... and so did its deletion.
+ # Everything it did not touch is main's.
+ assert _show(repo, "dodaios/core/beta.py") == "NAME = 'new'\n"
+ assert _show(repo, "tests/test_alpha.py") == "from dodaios.core.alpha import VALUE\n"
+ assert _show(repo, "app.py") == "VALUE = 2\n"
+ # Nothing of the package is left under the old name but the compatibility file.
+ assert {name for name in tree if name.startswith("jarvis/")} == {"jarvis/__init__.py"}
+ assert _show(repo, "jarvis/__init__.py") == _git(repo, "show", "main:jarvis/__init__.py")
+ check = ["--from", "jarvis", "--to", "dodaios", "--root", str(repo), "--check"]
+ assert codemod.main(check) == 0
+
+
+def test_the_script_of_the_move_commit_is_the_one_that_replays(repo):
+ """A branch never needs the script itself, and a later edit to it on main
+ cannot change what an old branch is carried across with."""
+ move = _move_on_main(repo)
+ _commit(repo, "main: retire the script", {agent_integrate.RENAME_SCRIPT: "raise SystemExit\n"})
+ _git(repo, "checkout", "-q", "feature")
+ _commit(repo, "feature work", {"jarvis/core/alpha.py": "from jarvis.core import gamma\n"})
+
+ report = agent_integrate.update("main", "merge", "", repo)
+
+ assert report["status"] == "updated" and report["package_move"] == move, report
+ assert _show(repo, "dodaios/core/alpha.py") == "from dodaios.core import gamma\n"
+ assert _show(repo, agent_integrate.RENAME_SCRIPT) == "raise SystemExit\n"
+
+
+def test_a_conflict_after_the_move_keeps_the_replay_and_says_how_to_go_on(repo):
+ move = _move_on_main(repo)
+ _commit(repo, "main work after the move", {"app.py": "VALUE = 2\n"})
+ _git(repo, "checkout", "-q", "feature")
+ _commit(
+ repo,
+ "feature work",
+ {"app.py": "VALUE = 3\n", "jarvis/core/alpha.py": "from jarvis.core import gamma\n"},
+ )
+
+ report = agent_integrate.update("main", "rebase", "", repo)
+
+ assert report["status"] == "conflict" and report["unresolved"] == ["app.py"]
+ # The branch is across the move and whole; what is left is an ordinary
+ # conflict between two trees of the new layout.
+ assert report["package_move"] == move
+ assert _git(repo, "status", "--porcelain").strip() == ""
+ assert _show(repo, "dodaios/core/alpha.py") == "from dodaios.core import gamma\n"
+ assert _show(repo, "app.py") == "VALUE = 3\n"
+
+
+def test_a_carried_branch_is_updated_by_merge_from_then_on(repo):
+ """A rebase would drop the merge that carries the move and replay the
+ branch's old-layout commits onto the new layout, file by file."""
+ move = _move_on_main(repo)
+ _feature_work(repo)
+ assert agent_integrate.update("main", "rebase", "", repo)["status"] == "updated"
+ _git(repo, "checkout", "-q", "main")
+ later = _commit(repo, "main work after the carry", {"app.py": "VALUE = 9\n"})
+ _git(repo, "checkout", "-q", "feature")
+ _commit(repo, "feature work in the new layout", {"dodaios/core/beta.py": "NAME = 'own'\n"})
+
+ assert agent_integrate.package_move("main", repo) is None
+ assert agent_integrate.carried_package_move("main", repo) == move
+ report = agent_integrate.update("main", "rebase", "", repo)
+
+ assert report["status"] == "updated" and report["package_move"] == move, report
+ assert _git(repo, "status", "--porcelain").strip() == ""
+ assert _git(repo, "merge-base", "--is-ancestor", later, "HEAD") == ""
+ assert _show(repo, "dodaios/core/alpha.py") == (
+ "from dodaios.core import beta, gamma\n\nVALUE = 2\n"
+ )
+ assert _show(repo, "dodaios/core/beta.py") == "NAME = 'own'\n"
+ assert _show(repo, "app.py") == "VALUE = 9\n"
+ assert {name for name in _tree(repo) if name.startswith("jarvis/")} == {"jarvis/__init__.py"}
+ check = ["--from", "jarvis", "--to", "dodaios", "--root", str(repo), "--check"]
+ assert codemod.main(check) == 0
+
+
+def test_a_conflict_on_a_carried_branch_is_a_merge_to_continue(repo):
+ move = _move_on_main(repo)
+ _feature_work(repo)
+ assert agent_integrate.update("main", "rebase", "", repo)["status"] == "updated"
+ head = _commit(repo, "feature work", {"app.py": "VALUE = 3\n"})
+ _git(repo, "checkout", "-q", "main")
+ _commit(repo, "main work after the carry", {"app.py": "VALUE = 9\n"})
+ _git(repo, "checkout", "-q", "feature")
+
+ report = agent_integrate.update("main", "rebase", "", repo)
+
+ assert report["status"] == "conflict" and report["unresolved"] == ["app.py"]
+ assert report["package_move"] == move
+ assert _git(repo, "rev-parse", "HEAD").strip() == head
+ assert _git(repo, "status", "--porcelain").strip() == ""
+
+
+def test_a_conflict_from_before_the_move_is_reported_against_that_commit(repo):
+ before = _commit(repo, "main work before the move", {"app.py": "VALUE = 2\n"})
+ _move_on_main(repo)
+ _git(repo, "checkout", "-q", "feature")
+ head = _commit(repo, "feature work", {"app.py": "VALUE = 3\n"})
+
+ report = agent_integrate.update("main", "rebase", "", repo)
+
+ assert report["status"] == "conflict"
+ assert report["unresolved"] == ["app.py"]
+ assert report["onto"] == before
+ # Nothing half-done: the branch is where it was, in the old layout.
+ assert _git(repo, "rev-parse", "HEAD").strip() == head
+ assert not (repo / "dodaios").exists()
+
+
+# --------------------------------------------------------------------------- the merge train
+
+
+class _FakeGh:
+ def __init__(self) -> None:
+ self.calls: list[tuple[str, ...]] = []
+
+ def __call__(self, *args: str) -> int:
+ self.calls.append(args)
+ return 0
+
+
+def _machines(tmp_path: Path, repo: Path) -> tuple[Path, Path, Path, dict]:
+ origin = tmp_path / "origin.git"
+ _git(tmp_path, "clone", "-q", "--bare", str(repo), str(origin))
+ clones = []
+ for name in ("integrate", "apply"):
+ clone = tmp_path / name
+ _git(tmp_path, "clone", "-q", str(origin), str(clone))
+ _git(clone, "config", "user.email", "[email protected]")
+ _git(clone, "config", "user.name", "t")
+ _git(clone, "config", "core.autocrlf", "false")
+ clones.append(clone)
+ plan = {
+ "repo": "example/project",
+ "main": _git(origin, "rev-parse", "main").strip(),
+ "queue": True,
+ "entries": [
+ {
+ "number": 3,
+ "branch": "feature",
+ "head": _git(origin, "rev-parse", "feature").strip(),
+ "id": "PR_node",
+ "action": "update",
+ "run_id": None,
+ "note": "",
+ }
+ ],
+ }
+ return origin, clones[0], clones[1], plan
+
+
+def _tick(tmp_path: Path, name: str, origin: Path, integrate: Path, applier: Path, plan: dict):
+ work = tmp_path / name
+ for clone in (integrate, applier):
+ _git(clone, "fetch", "-q", "origin")
+ plan = json.loads(json.dumps(plan))
+ plan["entries"][0]["head"] = _git(origin, "rev-parse", "feature").strip()
+ assert agent_integrate.integrate_merge(work, plan, integrate) == 0
+ agent_integrate.integrate_finish(work, plan)
+ agent_integrate.cleanup_worktrees(work, integrate)
+ state = json.loads((work / "state" / "pr-3.json").read_text(encoding="utf-8"))
+ outcome = agent_integrate.apply_update(work, plan, plan["entries"][0], False, applier)
+ return state, outcome
+
+
+def test_the_train_carries_a_pull_request_across_the_move_in_two_ticks(tmp_path, repo, monkeypatch):
+ before = _commit(repo, "main work before the move", {"app.py": "VALUE = 2\n"})
+ move = _move_on_main(repo)
+ _feature_work(repo)
+ origin, integrate, applier, plan = _machines(tmp_path, repo)
+ monkeypatch.setattr(agent_integrate, "gh", _FakeGh())
+
+ # Tick 1: up to the last commit of the old layout, an ordinary merge.
+ state, outcome = _tick(tmp_path, "tick-1", origin, integrate, applier, plan)
+ assert state["status"] == "ready" and state["onto"] == before, state
+ assert outcome.startswith("updated with main"), outcome
+ assert "jarvis/core/delta.py" in _tree(origin, "feature")
+ assert _git(origin, "show", "feature:app.py") == "VALUE = 2\n"
+
+ # Tick 2: the move is replayed on top of that.
+ state, outcome = _tick(tmp_path, "tick-2", origin, integrate, applier, plan)
+ assert state["status"] == "ready" and "onto" not in state, state
+ assert outcome.startswith("updated with main"), outcome
+ tree = _tree(origin, "feature")
+ assert "dodaios/core/delta.py" in tree and "jarvis/core/delta.py" not in tree
+ assert _git(origin, "show", "feature:dodaios/core/alpha.py").startswith(
+ "from dodaios.core import beta, gamma"
+ )
+ assert _git(origin, "merge-base", "--is-ancestor", move, "feature") == ""
+
+
+def test_apply_rejects_a_stopping_point_that_is_not_in_mains_history(tmp_path, repo, monkeypatch):
+ _commit(repo, "main work", {"app.py": "VALUE = 2\n"})
+ _feature_work(repo)
+ origin, integrate, applier, plan = _machines(tmp_path, repo)
+ monkeypatch.setattr(agent_integrate, "gh", _FakeGh())
+ work = tmp_path / "train"
+ assert agent_integrate.integrate_merge(work, plan, integrate) == 0
+ agent_integrate.integrate_finish(work, plan)
+ agent_integrate.cleanup_worktrees(work, integrate)
+ state_file = work / "state" / "pr-3.json"
+ state = json.loads(state_file.read_text(encoding="utf-8"))
+ # A bundle that claims to stop at the pull request's own head.
+ state["onto"] = plan["entries"][0]["head"]
+ state_file.write_text(json.dumps(state), encoding="utf-8")
+
+ outcome = agent_integrate.apply_update(work, plan, plan["entries"][0], False, applier)
+
+ assert outcome.startswith("update bundle rejected"), outcome
+ assert _git(origin, "rev-parse", "feature").strip() == plan["entries"][0]["head"]
+
+
+# --------------------------------------------------------------------------- CI lanes
+
+_LANE_PATHS = [
+ "jarvis/ui/web/frontend/src/lib/tasksApi.ts",
+ "jarvis/ui/web/update_routes.py",
+ "jarvis/realtime/factory.py",
+ "jarvis/cli_ctl/commands/system.py",
+ "jarvis/overlay/drop_target.py",
+ "jarvis/society/browser/runner.py",
+ "jarvis/core/branding.py",
+ "jarvis/setup/prefetch.py",
+ "jarvis/__main__.py",
+ "jarvis/agent_runtimes/hermes.py",
+ "jarvis/assets/browser/requirements.lock",
+ "jarvis/society/roster.py",
+ "jarvis/ui/desktop_app.py",
+ "jarvis/brain/router.py",
+]
+
+
[email protected]("path", _LANE_PATHS)
+def test_both_names_of_the_package_directory_turn_on_the_same_lanes(path):
+ old = classify_changes.classify([path])
+ new = classify_changes.classify([path.replace("jarvis/", "dodaios/", 1)])
+ assert old == new
+ assert old["python"] is True and old["full"] is False
+
+
+def test_every_lane_a_package_change_can_reach_is_reached_under_both_names():
+ reached_old: set[str] = set()
+ reached_new: set[str] = set()
+ for path in _LANE_PATHS:
+ for seen, spelled in ((reached_old, path), (reached_new, "dodaios" + path[6:])):
+ seen.update(lane for lane, on in classify_changes.classify([spelled]).items() if on)
+ assert reached_old == reached_new
+ assert reached_old >= set(classify_changes.LANES) - {"full"}
+
+
+def test_a_file_that_is_not_in_the_package_is_not_mistaken_for_it():
+ assert classify_changes.classify(["jarvis.spec"])["macos_desktop"] is True
+ assert classify_changes.classify(["docs/jarvis/notes.md"])["frontend"] is False
+ assert classify_changes.classify(["dodaios.md"]) == classify_changes.classify(["notes.md"])
+
+
+def _after_the_move(relative: str, tmp_path: Path):
+ """A script of this repository as the move commit will leave it, loaded."""
+ rewriter = codemod.Rewriter.from_tree(_REPO_ROOT, "jarvis", "dodaios")
+ source = rewriter.transform(relative, (_REPO_ROOT / relative).read_bytes())
+ path = tmp_path / ("moved_" + Path(relative).name)
+ path.write_bytes(source)
+ spec = importlib.util.spec_from_file_location(path.stem, path)
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def test_the_classifier_still_reads_both_names_once_it_has_been_moved_itself(tmp_path):
+ moved = _after_the_move("scripts/ci/classify_changes.py", tmp_path)
+ # The lane table it borrows moves in the same commit.
+ moved.agent_runtime_suite = _after_the_move("scripts/ci/agent_runtime_suite.py", tmp_path)
+ for path in _LANE_PATHS:
+ new = moved.classify([path.replace("jarvis/", "dodaios/", 1)])
+ assert new == classify_changes.classify([path]), path
+ assert new == moved.classify([path]), path
+
+
+def test_the_integration_script_keeps_its_two_package_names_through_the_move(tmp_path):
+ relative = "scripts/ci/agent_integrate.py"
+ rewriter = codemod.Rewriter.from_tree(_REPO_ROOT, "jarvis", "dodaios")
+ source = rewriter.transform(relative, (_REPO_ROOT / relative).read_bytes()).decode("utf-8")
+ assert 'OLD_PACKAGE = "jarvis"' in source and 'NEW_PACKAGE = "dodaios"' in source
+ assert "ui/web/frontend" in source and '"jarvis/ui/web/frontend"' not in source
diff --git a/tests/unit/ci/test_rewrite_package.py b/tests/unit/ci/test_rewrite_package.py
new file mode 100644
index 0000000000..c685cc92bb
--- /dev/null
+++ b/tests/unit/ci/test_rewrite_package.py
@@ -0,0 +1,874 @@
+"""The package rename codemod, run on a small real git repository.
+
+The file is full of the OLD package name on purpose: it is the codemod's input
+and expectation, so the codemod itself never rewrites it (``FROZEN_FILES``).
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from scripts.rename import rewrite_package as codemod
+
+OLD, NEW = "jarvis", "dodaios"
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+_NO_WINDOW = getattr(subprocess, "CREATE_NO_WINDOW", 0)
+
+_MAIN = '''"""Start the app."""
+import sys
+
+
+def main() -> int:
+ print("ran", __spec__.name if __spec__ else None, "as", __name__)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
+'''
+
+_PYPROJECT = """[project]
+name = "personal-jarvis"
+
+[project.scripts]
+jarvis = "jarvis.__main__:main"
+personal-jarvis = "jarvis.__main__:main"
+jarvisctl = "jarvis.cli_ctl.__main__:main"
+
+[project.entry-points."jarvis.brain"]
+openai = "jarvis.plugins.brain.openai:OpenAIBrain"
+
+[project.entry-points."jarvis.tool"]
+click = "jarvis.plugins.tool.click:ClickTool"
+
+[tool.setuptools.packages.find]
+include = ["jarvis*", "conductor*"]
+
+[tool.setuptools.package-data]
+conductor = ["core/schema.sql"]
+jarvis = [
+ "ui/web/dist/**/*",
+ # read by jarvis/brain/persona.py
+ "brain/PERSONA.md",
+]
+
+[tool.setuptools.data-files]
+"share/personal-jarvis/docs" = ["docs/**/*.md"]
+"""
+
+_WORKFLOW = """on:
+ pull_request:
+ paths:
+ - "jarvis/appshot/**"
+ - "jarvis/ui/web/appshot_routes.py"
+ - "tests/unit/appshot/**"
+env:
+ JARVIS_CONFIG: /app/data/jarvis.toml
+jobs:
+ lint:
+ steps:
+ - run: python -m ruff check jarvis/
+ - run: python -m mypy jarvis tests
+ - run: python -c "import jarvis.cli_ctl.__main__"
+ - run: python -m jarvis.cli_ctl --help
+ - run: pytest --cov=jarvis tests
+ working-directory: jarvis/ui/web/frontend
+ - run: echo "${{ hashFiles('jarvis/agent_runtimes/runtime-versions.json') }}"
+ - run: jarvis serve --headless
+"""
+
+_DOCKERFILE = """WORKDIR /build/jarvis/ui/web/frontend
+COPY jarvis/ui/web/frontend/package.json ./
+COPY jarvis ./jarvis
+COPY --from=web /build/jarvis/ui/web/dist ./jarvis/ui/web/dist
+RUN useradd --system jarvis && chown -R jarvis:jarvis /app/data
+USER jarvis
+ENV JARVIS_CONFIG=/app/data/jarvis.toml
+# docker run -v jarvis-data:/app/data personal-jarvis
+CMD ["python", "-m", "jarvis.ui.web.launcher", "--headless"]
+"""
+
+_SPEC = """FRONTEND_DIST = PROJECT_ROOT / "jarvis" / "ui" / "web" / "dist"
+_package_root = PROJECT_ROOT / "jarvis"
+CLI_EXE_NAME = "jarvis"
+MACOS_BUNDLE_IDENTIFIER = "ai.personaljarvis.desktop"
+datas = [(str(PROJECT_ROOT / "jarvis.toml"), ".")]
+datas.append((str(PROJECT_ROOT / "jarvis/society/x.py"), "jarvis/society"))
+hiddenimports = collect_submodules("jarvis.plugins")
+ENTRY = ["jarvis/__main__.py"]
+print("[jarvis.spec] icon is missing")
+"""
+
+_TEST_MODULE = """import importlib
+import logging
+import sys
+
+import jarvis
+from jarvis.core import branding
+from jarvis.core.config import load
+
+
+def test_it(monkeypatch, caplog):
+ monkeypatch.setattr("jarvis.core.config.load", lambda: None)
+ monkeypatch.setitem(sys.modules, "jarvis.realtime", None)
+ module = importlib.import_module("jarvis.ui.web.launcher")
+ runtime = sys.modules.get("jarvis.society.runtime")
+ with caplog.at_level(logging.INFO, logger="jarvis.core.config"):
+ logging.getLogger("jarvis").info("x")
+ argv = [sys.executable, "-m", "jarvis", "--headless"]
+ other = [sys.executable, "-m", "jarvis.ui.relauncher", "1", "."]
+ root = Path(jarvis.__file__).parent
+ version = jarvis.__version__
+ session = make(surface="jarvis", opened_by="jarvis")
+ for surface in ("jarvis", "agents"):
+ pass
+"""
+
+_BUILD_PS1 = """$FrontendDist = Join-Path $RepoRoot "jarvis\\ui\\web\\dist"
+$InitFile = Join-Path $RepoRoot "jarvis\\__init__.py"
+if (-not (Test-Path $SpecFile)) { Stop-WithError "jarvis.spec not found" }
+$IconFile = Join-Path $RepoRoot "assets\\icons\\jarvis.ico"
+"""
+
+_GUIDE = """# Guide
+
+The package lives in `jarvis/` (see `jarvis/core/config.py:12` and
+`jarvis/{core,ui}/`). Import it with `from jarvis.core import branding`; plugins
+import nothing from `jarvis.*`. The removed module `jarvis/awareness/probe.py`
+is gone. Start it with `jarvis serve` or `python -m jarvis`; settings are in
+`jarvis.toml`, data in `~/.jarvis/` and `data/jarvis.db`.
+Hey Jarvis, what is on today?
+"""
+
+_WEB_SOURCE = """// Kept in step with jarvis.ui.web.launcher (jarvis/ui/web/launcher.py).
+const STOP_KEY = "jarvis.ui.walkStop";
+const GROUPS = [{ group: "jarvis.brain" }];
+const own = /^jarvis\\//i.test(name) ? name.slice("jarvis/".length) : null;
+// "jarvis/gmail" is the Gmail plugin.
+"""
+
+_HISTORY = "- moved `jarvis/core/old.py`; run `python -m jarvis.ui.web.launcher`\n"
+
+FILES: dict[str, str] = {
+ "jarvis/__init__.py": '"""The package."""\n\n__version__ = "1.2.3"\n',
+ "jarvis/__main__.py": _MAIN,
+ "jarvis/core/__init__.py": "",
+ "jarvis/core/branding.py": 'NAME = "Thing"\nSTATE: list[str] = []\n',
+ "jarvis/core/config.py": (
+ "from jarvis.core.branding import NAME\n\n\ndef load() -> str:\n return NAME\n"
+ ),
+ "jarvis/brain/__init__.py": "from jarvis.core import branding as branding\n",
+ "jarvis/plugins/__init__.py": "",
+ "jarvis/appshot/__init__.py": "",
+ "jarvis/agent_runtimes/runtime-versions.json": "{}\n",
+ "jarvis/cli_ctl/__init__.py": "",
+ "jarvis/cli_ctl/__main__.py": _MAIN,
+ "jarvis/realtime/__init__.py": "",
+ "jarvis/society/__init__.py": "",
+ "jarvis/society/x.py": "",
+ "jarvis/ui/__init__.py": "",
+ "jarvis/ui/relauncher.py": _MAIN,
+ "jarvis/ui/web/__init__.py": "",
+ "jarvis/ui/web/launcher.py": _MAIN,
+ "jarvis/ui/web/dist/index.html": '<script src="jarvis/ui/web/x.js">jarvis.core.y</script>\n',
+ "jarvis/ui/web/frontend/src/app.ts": _WEB_SOURCE,
+ "jarvis/ui/web/frontend/src/i18n/locales/en.json": (
+ '{"hint": "Run python -m jarvis.ui.web.launcher, see jarvis/core/config.py"}\n'
+ ),
+ "jarvis/mcp/__init__.py": "",
+ "jarvis/mcp/server.py": _MAIN,
+ "jarvis/mcp/agents/__init__.py": "",
+ "jarvis/mcp/agents/bridge.py": _MAIN,
+ "pyproject.toml": _PYPROJECT,
+ "jarvis.spec": _SPEC,
+ "jarvis.toml.example": "# settings\n[brain]\n",
+ "Dockerfile": _DOCKERFILE,
+ ".github/workflows/ci.yml": _WORKFLOW,
+ "scripts/ci/german-allowlist.txt": "jarvis/brain/__init__.py\njarvis/core/config.py\n",
+ "packaging/build.ps1": _BUILD_PS1,
+ ".gitignore": "/jarvis.toml\njarvis/ui/web/frontend/node_modules/\n.jarvis-managed-install\n",
+ "docs/guide.md": _GUIDE,
+ "CHANGELOG.md": _HISTORY,
+ "docs/BUGS.md": _HISTORY,
+ "docs/supply-chain/wave3.md": _HISTORY,
+ "docs/superpowers/plans/plan.md": _HISTORY,
+ "tests/test_core.py": _TEST_MODULE,
+ "legacy_samples.txt": "\n".join(
+ sample for entry in codemod.LEGACY_IDENTIFIERS for sample in entry.samples
+ )
+ + "\n",
+}
+
+
+def _git(repo: Path, *args: str) -> str:
+ return subprocess.run(
+ ["git", "-C", str(repo), *args],
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ check=True,
+ creationflags=_NO_WINDOW,
+ ).stdout
+
+
+def _write(repo: Path, files: dict[str, str]) -> None:
+ for name, text in files.items():
+ path = repo / name
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(text, encoding="utf-8", newline="")
+
+
+def repo(tmp_path):
+ root = tmp_path / "repo"
+ root.mkdir()
+ _git(root, "init", "-q", "-b", "main")
+ _git(root, "config", "user.email", "[email protected]")
+ _git(root, "config", "user.name", "t")
+ _git(root, "config", "core.autocrlf", "false")
+ _write(root, FILES)
+ _git(root, "add", "-f", ".")
+ _git(root, "commit", "-q", "-m", "base")
+ return root
+
+
+def _read(repo: Path, name: str) -> str:
+ return (repo / name).read_text(encoding="utf-8")
+
+
+def _tracked(repo: Path) -> set[str]:
+ return set(_git(repo, "ls-files").split())
+
+
+def _rewriter() -> codemod.Rewriter:
+ """A rewriter that knows the small package above."""
+ paths = [name[len(OLD) + 1 :] for name in FILES if name.startswith(OLD + "/")]
+ return codemod.Rewriter(OLD, NEW, paths, groups=["brain", "tool"])
+
+
+def _rewritten(text: str, path: str = "notes/sample.py") -> str:
+ return _rewriter().transform(path, text.encode("utf-8")).decode("utf-8")
+
+
+# --------------------------------------------------------------------------- the run
+
+
+def test_dry_run_reports_and_changes_nothing(repo, capsys):
+ before = _git(repo, "status", "--porcelain")
+ assert codemod.main(["--from", OLD, "--to", NEW, "--root", str(repo), "--dry-run"]) == 0
+ out = capsys.readouterr().out
+ assert "move jarvis/__init__.py -> dodaios/__init__.py" in out
+ assert "rewrite pyproject.toml:" in out
+ assert "file(s) to move" in out and "ambiguous hit(s)" in out
+ assert _git(repo, "status", "--porcelain") == before
+ assert not (repo / NEW).exists()
+ assert _read(repo, "jarvis/core/config.py") == FILES["jarvis/core/config.py"]
+
+
+def test_a_run_moves_the_package_and_stages_exactly_its_work(repo):
+ (repo / "notes.txt").write_text("someone else's untracked work\n", encoding="utf-8")
+ report = codemod.apply(repo, OLD, NEW)
+
+ assert not report.blocked
+ tracked = _tracked(repo)
+ package_files = {name for name in FILES if name.startswith("jarvis/")}
+ assert {NEW + name[len(OLD) :] for name in package_files} <= tracked
+ # Only the compatibility package is left under the old name.
+ assert {name for name in tracked if name.startswith("jarvis/")} == {"jarvis/__init__.py"}
+ assert codemod.STUB_MARKER in _read(repo, "jarvis/__init__.py")
+ # The frontend source and the built bundle moved with the package.
+ assert "dodaios/ui/web/frontend/src/app.ts" in tracked
+ assert "dodaios/ui/web/dist/index.html" in tracked
+ # Everything the run wrote is staged; the stranger's file is not.
+ assert _git(repo, "diff", "--name-only") == ""
+ assert "notes.txt" not in _git(repo, "diff", "--cached", "--name-only")
+ renames = _git(repo, "diff", "--cached", "--name-status", "-M")
+ assert "jarvis/core/branding.py\tdodaios/core/branding.py" in renames
+
+
+def test_imports_and_module_paths_are_rewritten(repo):
+ codemod.apply(repo, OLD, NEW)
+
+ assert _read(repo, "dodaios/core/config.py").startswith("from dodaios.core.branding import")
+ assert (
+ _read(repo, "dodaios/brain/__init__.py")
+ == "from dodaios.core import branding as branding\n"
+ )
+ test_module = _read(repo, "tests/test_core.py")
+ for expected in (
+ "import dodaios\n",
+ "from dodaios.core import branding",
+ "from dodaios.core.config import load",
+ 'monkeypatch.setattr("dodaios.core.config.load"',
+ 'monkeypatch.setitem(sys.modules, "dodaios.realtime", None)',
+ 'importlib.import_module("dodaios.ui.web.launcher")',
+ 'sys.modules.get("dodaios.society.runtime")',
+ 'logger="dodaios.core.config"',
+ 'logging.getLogger("dodaios")',
+ '"-m", "dodaios", "--headless"',
+ '"-m", "dodaios.ui.relauncher"',
+ "Path(dodaios.__file__)",
+ "dodaios.__version__",
+ # Names that only look like the package stay.
+ 'make(surface="jarvis", opened_by="jarvis")',
+ 'for surface in ("jarvis", "agents")',
+ ):
+ assert expected in test_module, expected
+ assert "jarvis." not in test_module
+
+
+def test_pyproject_moves_targets_and_keeps_command_and_group_names(repo):
+ codemod.apply(repo, OLD, NEW)
+ text = _read(repo, "pyproject.toml")
+
+ assert 'name = "personal-jarvis"' in text
+ assert 'jarvis = "dodaios.__main__:main"' in text
+ assert 'personal-jarvis = "dodaios.__main__:main"' in text
+ assert 'jarvisctl = "dodaios.cli_ctl.__main__:main"' in text
+ assert '[project.entry-points."jarvis.brain"]' in text
+ assert '[project.entry-points."jarvis.tool"]' in text
+ assert 'openai = "dodaios.plugins.brain.openai:OpenAIBrain"' in text
+ assert 'click = "dodaios.plugins.tool.click:ClickTool"' in text
+ # Both packages ship: the real one and the compatibility one.
+ assert 'include = ["dodaios*", "jarvis*", "conductor*"]' in text
+ assert "\ndodaios = [\n" in text and "\njarvis = [\n" not in text
+ assert "# read by dodaios/brain/persona.py" in text
+ assert '"share/personal-jarvis/docs"' in text
+
+
+def test_paths_are_rewritten_in_workflows_packaging_and_allowlists(repo):
+ codemod.apply(repo, OLD, NEW)
+
+ workflow = _read(repo, ".github/workflows/ci.yml")
+ for expected in (
+ '- "dodaios/appshot/**"',
+ '- "dodaios/ui/web/appshot_routes.py"',
+ "ruff check dodaios/",
+ "mypy dodaios tests",
+ 'python -c "import dodaios.cli_ctl.__main__"',
+ "python -m dodaios.cli_ctl --help",
+ "--cov=dodaios tests",
+ "working-directory: dodaios/ui/web/frontend",
+ "hashFiles('dodaios/agent_runtimes/runtime-versions.json')",
+ "JARVIS_CONFIG: /app/data/jarvis.toml",
+ "run: jarvis serve --headless",
+ ):
+ assert expected in workflow, expected
+ assert _read(repo, "scripts/ci/german-allowlist.txt") == (
+ "dodaios/brain/__init__.py\ndodaios/core/config.py\n"
+ )
+ assert _read(repo, ".gitignore") == (
+ "/jarvis.toml\ndodaios/ui/web/frontend/node_modules/\n.jarvis-managed-install\n"
+ )
+ assert _read(repo, "packaging/build.ps1") == _BUILD_PS1.replace(
+ '"jarvis\\ui', '"dodaios\\ui'
+ ).replace('"jarvis\\__init__', '"dodaios\\__init__')
+
+ spec = _read(repo, "jarvis.spec") # the file keeps its name, its content moves
+ for expected in (
+ 'PROJECT_ROOT / "dodaios" / "ui" / "web" / "dist"',
+ '_package_root = PROJECT_ROOT / "dodaios"',
+ 'CLI_EXE_NAME = "jarvis"',
+ '"ai.personaljarvis.desktop"',
+ 'PROJECT_ROOT / "jarvis.toml"',
+ '"dodaios/society/x.py"), "dodaios/society")',
+ 'collect_submodules("dodaios.plugins")',
+ '["dodaios/__main__.py"]',
+ "[jarvis.spec] icon is missing",
+ ):
+ assert expected in spec, expected
+
+ docker = _read(repo, "Dockerfile")
+ assert "WORKDIR /build/dodaios/ui/web/frontend" in docker
+ assert "COPY dodaios ./dodaios\nCOPY jarvis ./jarvis\n" in docker
+ assert "COPY --from=web /build/dodaios/ui/web/dist ./dodaios/ui/web/dist" in docker
+ assert "useradd --system jarvis && chown -R jarvis:jarvis /app/data" in docker
+ assert "-v jarvis-data:/app/data personal-jarvis" in docker
+ assert '"-m", "dodaios.ui.web.launcher"' in docker
+
+
+def test_documents_follow_the_package_and_keep_names(repo):
+ codemod.apply(repo, OLD, NEW)
+ guide = _read(repo, "docs/guide.md")
+
+ for expected in (
+ "lives in `dodaios/` (see `dodaios/core/config.py:12`",
+ "`dodaios/{core,ui}/`",
+ "`from dodaios.core import branding`",
+ "nothing from `dodaios.*`",
+ "`dodaios/awareness/probe.py`", # a removed module is still a path of the package
+ "`jarvis serve` or `python -m dodaios`",
+ "`jarvis.toml`, data in `~/.jarvis/` and `data/jarvis.db`",
+ "Hey Jarvis, what is on today?",
+ ):
+ assert expected in guide, expected
+
+
+def test_web_sources_keep_storage_keys_and_tool_prefixes(repo):
+ codemod.apply(repo, OLD, NEW)
+ source = _read(repo, "dodaios/ui/web/frontend/src/app.ts")
+
+ assert "dodaios.ui.web.launcher (dodaios/ui/web/launcher.py)" in source
+ assert 'const STOP_KEY = "jarvis.ui.walkStop";' in source
+ assert '{ group: "jarvis.brain" }' in source
+ assert 'name.slice("jarvis/".length)' in source
+ assert '"jarvis/gmail" is the Gmail plugin' in source
+
+
+# --------------------------------------------------------------------------- what stays
+
+
+ "entry", codemod.LEGACY_IDENTIFIERS, ids=[entry.name for entry in codemod.LEGACY_IDENTIFIERS]
+)
+def test_every_legacy_identifier_survives(entry):
+ assert entry.reason and entry.samples
+ for sample in entry.samples:
+ for path in ("notes/sample.py", "notes/sample.md", "notes/sample.toml", "notes/run.sh"):
+ assert _rewritten(sample, path) == sample, (entry.name, path, sample)
+
+
+def test_legacy_identifiers_survive_a_whole_run(repo):
+ codemod.apply(repo, OLD, NEW)
+ assert _read(repo, "legacy_samples.txt") == FILES["legacy_samples.txt"]
+ assert _read(repo, "jarvis.toml.example") == FILES["jarvis.toml.example"]
+ assert "jarvis.spec" in _tracked(repo) and "jarvis.toml.example" in _tracked(repo)
+
+
+ "frozen", codemod.FROZEN_FILES, ids=[frozen.glob for frozen in codemod.FROZEN_FILES]
+)
+def test_every_frozen_file_keeps_its_content(frozen):
+ assert frozen.reason
+ text = "see jarvis/core/config.py and `from jarvis.core import branding`\n"
+ assert _rewritten(text) != text # the same words anywhere else are rewritten
+ for package in (OLD, NEW):
+ path = frozen.glob.replace("{pkg}", package).replace("**/", "web/").replace("**", "a/b.md")
+ assert _rewritten(text, path) == text, path
+
+
+def test_history_and_generated_files_are_moved_but_not_rewritten(repo):
+ codemod.apply(repo, OLD, NEW)
+ for name in ("CHANGELOG.md", "docs/BUGS.md", "docs/supply-chain/wave3.md"):
+ assert _read(repo, name) == _HISTORY, name
+ assert _read(repo, "docs/superpowers/plans/plan.md") == _HISTORY
+ assert _read(repo, "dodaios/ui/web/dist/index.html") == FILES["jarvis/ui/web/dist/index.html"]
+ locale = "ui/web/frontend/src/i18n/locales/en.json"
+ assert _read(repo, f"dodaios/{locale}") == FILES[f"jarvis/{locale}"]
+
+
+def test_a_line_with_the_pragma_is_left_alone():
+ text = (
+ "from jarvis.core import branding # rename-keep: read by an old updater\n"
+ "from jarvis.core import config\n"
+ )
+ assert _rewritten(text) == text.replace(
+ "from jarvis.core import config", "from dodaios.core import config"
+ )
+
+
+ "text",
+ [
+ 'key = "jarvis"',
+ "Ask Jarvis, or type `jarvis update`.",
+ 'COOKIE = "jarvis_session"',
+ "mcp_servers.jarvis.required=true",
+ "extras.jarvis_figure",
+ 'home / ".config" / "jarvis" / "agent.env"',
+ 'link = bin_dir / "jarvis"',
+ 'service_account_path = "~/.config/jarvis/vertex-sa.json"',
+ "ExecStart=/home/jarvis/jarvis-venv/bin/jarvis serve",
+ 'log = logging.getLogger("jarvis.wake.vosk")', # a logger name, not a module
+ 'PLUGIN_GROUP = "jarvis.brain"',
+ 'entry_points(group="jarvis.tool")',
+ "jarvis.toml jarvis.db jarvis.lock jarvis.spec jarvis.ico",
+ "hauptjarvis subjarvis_worker personaljarvis.ai",
+ r'pattern = re.compile(r"\bjarvis\b")',
+ ],
+)
+def test_names_that_only_look_like_the_package_are_kept(text):
+ assert _rewritten(text) == text
+
+
+ ("text", "expected"),
+ [
+ ("import jarvis", "import dodaios"),
+ ("from jarvis import __version__", "from dodaios import __version__"),
+ ("import jarvis.brain", "import dodaios.brain"),
+ ("from jarvis.brain import router", "from dodaios.brain import router"),
+ ("x = jarvis.core.config.load()", "x = dodaios.core.config.load()"),
+ ('"-m", "jarvis.mcp.server"', '"-m", "dodaios.mcp.server"'),
+ ("python -m jarvis.mcp.agents.bridge", "python -m dodaios.mcp.agents.bridge"),
+ ('find_spec("jarvis")', 'find_spec("dodaios")'),
+ ('patch("jarvis.brain")', 'patch("dodaios.brain")'),
+ ('"jarvis.brain:Router"', '"dodaios.brain:Router"'),
+ (r're.compile(r"^from\s+jarvis\.core\b")', r're.compile(r"^from\s+dodaios\.core\b")'),
+ ('root / "jarvis" / "core"', 'root / "dodaios" / "core"'),
+ ('os.path.join(root, "jarvis", "ui")', 'os.path.join(root, "dodaios", "ui")'),
+ ('(tmp_path / "jarvis").mkdir()', '(tmp_path / "dodaios").mkdir()'),
+ ('path.startswith("jarvis/")', 'path.startswith("dodaios/")'),
+ ("git add jarvis/core/config.py", "git add dodaios/core/config.py"),
+ ("site-packages/jarvis/core/x.py", "site-packages/dodaios/core/x.py"),
+ (
+ "diff --git a/jarvis/foo.py b/jarvis/foo.py",
+ "diff --git a/dodaios/foo.py b/dodaios/foo.py",
+ ),
+ ('Join-Path $Root "jarvis\\ui\\web"', 'Join-Path $Root "dodaios\\ui\\web"'),
+ ('_CODE_ROOTS = ("jarvis", "scripts")', '_CODE_ROOTS = ("dodaios", "scripts")'),
+ ('for root in ("jarvis", "tests"):', 'for root in ("dodaios", "tests"):'),
+ ('argv = [\n "-m",\n "jarvis",\n]', 'argv = [\n "-m",\n "dodaios",\n]'),
+ (
+ 'import jarvis\n\nmonkeypatch.setattr(jarvis, "accounts", fake)\n',
+ 'import dodaios\n\nmonkeypatch.setattr(dodaios, "accounts", fake)\n',
+ ),
+ ],
+)
+def test_references_to_the_package_are_rewritten(text, expected):
+ assert _rewritten(text) == expected
+
+
+# --------------------------------------------------------------------------- ambiguous
+
+
+def test_undecidable_hits_are_reported_with_their_line_and_left_alone(repo):
+ notes = (
+ "# notes\n"
+ 'FORBIDDEN = ("fastapi", "jarvis.brain", "jarvis.core.config")\n'
+ 'branch = f"jarvis/{slug}"\n'
+ 'model = "jarvis/gpt-5.2"\n'
+ )
+ _write(repo, {"notes.py": notes})
+ _git(repo, "add", "notes.py")
+
+ report, contents = codemod.plan(repo, OLD, NEW)
+
+ found = {(hit.path, hit.line): hit.reason for hit in report.ambiguous}
+ assert ("notes.py", 2) in found and "plugin group or module" in found[("notes.py", 2)]
+ assert ("notes.py", 3) in found and "placeholder" in found[("notes.py", 3)]
+ assert ("notes.py", 4) in found and "not in the package" in found[("notes.py", 4)]
+ rewritten = contents["notes.py"].decode("utf-8")
+ # The decidable half of line 2 moved; the undecidable names are untouched.
+ assert '("fastapi", "jarvis.brain", "dodaios.core.config")' in rewritten
+ assert 'f"jarvis/{slug}"' in rewritten and '"jarvis/gpt-5.2"' in rewritten
+ rendered = report.ambiguous[0].render()
+ assert rendered.startswith("notes.py:2:") or "notes.py:" in rendered
+
+
+ "text",
+ [
+ 'if any(name.startswith("jarvis.") for name in sys.modules):\n',
+ "offenders = [m for m in imported if m.startswith('jarvis.')]\n",
+ 'if name.startswith("jarvis"):\n',
+ 'PREFIXES = ("mcp_jarvis_", "jarvis.")\n',
+ ],
+)
+def test_a_guard_over_module_names_is_reported_and_left_alone(text):
+ """Kept silently, a test that forbids imports of the package would go on
+ passing while it no longer looks at a single module."""
+ data, result = _rewriter().rewrite("tests/test_guard.py", text.encode("utf-8"))
+
+ assert data.decode("utf-8") == text
+ assert [hit.line for hit in result.ambiguous] == [1]
+
+
+def test_the_word_from_before_the_name_is_an_import_only_with_an_import():
+ text = (
+ "from jarvis import __version__\n"
+ 'assert sent.startswith("[assignment from jarvis]")\n'
+ "task = \"Type the sentence 'hello from jarvis' into it.\"\n"
+ 'assert "from jarvis" not in generated_code\n'
+ 'offending = [ln for ln in lines if ln.startswith(("from jarvis", "import jarvis"))]\n'
+ )
+ data, result = _rewriter().rewrite("tests/test_prose.py", text.encode("utf-8"))
+
+ # The start of an import statement on its own is one a guard tests for;
+ # the same two words inside a sentence are prose.
+ assert data.decode("utf-8") == (
+ "from dodaios import __version__\n"
+ 'assert sent.startswith("[assignment from jarvis]")\n'
+ "task = \"Type the sentence 'hello from jarvis' into it.\"\n"
+ 'assert "from dodaios" not in generated_code\n'
+ 'offending = [ln for ln in lines if ln.startswith(("from dodaios", "import dodaios"))]\n'
+ )
+ assert result.ambiguous == []
+
+
+def test_a_lookup_in_the_package_data_table_follows_its_key():
+ """pyproject's package-data key moves; a test that reads the table by
+ that key has to move with it, and no other lookup may."""
+ text = (
+ 'direct = pyproject["tool"]["setuptools"]["package-data"]["jarvis"]\n'
+ 'patterns = data.get("tool", {}).get("setuptools", {}).get("package-data", {})\n'
+ 'assert "assets/**/*" in patterns.get("jarvis", [])\n'
+ 'assert "ui/web/dist/*" in patterns["jarvis"]\n'
+ 'assert scripts["jarvis"] == entry and surfaces.get("jarvis") is None\n'
+ )
+
+ assert _rewritten(text, "tests/test_packaging.py") == (
+ 'direct = pyproject["tool"]["setuptools"]["package-data"]["dodaios"]\n'
+ 'patterns = data.get("tool", {}).get("setuptools", {}).get("package-data", {})\n'
+ 'assert "assets/**/*" in patterns.get("dodaios", [])\n'
+ 'assert "ui/web/dist/*" in patterns["dodaios"]\n'
+ 'assert scripts["jarvis"] == entry and surfaces.get("jarvis") is None\n'
+ )
+
+
+def test_a_local_variable_named_like_the_package_is_not_an_import():
+ text = "jarvis = roster.lead()\nprint(jarvis.core, jarvis.agent_id)\n"
+ rewriter = _rewriter()
+ data, result = rewriter.rewrite("notes/sample.py", text.encode("utf-8"))
+ assert data.decode("utf-8") == text
+ assert [hit.line for hit in result.ambiguous] == [2]
+
+
+# --------------------------------------------------------------------------- repeatable
+
+
[email protected]("name", sorted(FILES))
+def test_a_checkout_with_crlf_line_endings_is_rewritten_the_same(name):
+ """The move is made in a working tree and replayed on blobs; both must
+ decide alike whatever line endings the checkout has."""
+ rewriter = _rewriter()
+ lf = FILES[name].encode("utf-8")
+ crlf = lf.replace(b"\n", b"\r\n")
+ assert rewriter.transform(name, crlf) == rewriter.transform(name, lf).replace(b"\n", b"\r\n")
+
+
+def test_a_second_run_changes_nothing(repo):
+ codemod.apply(repo, OLD, NEW)
+ _git(repo, "commit", "-q", "-m", "move")
+ tree = _git(repo, "rev-parse", "HEAD^{tree}")
+
+ again = codemod.apply(repo, OLD, NEW)
+
+ assert not again.pending and not again.blocked
+ assert _git(repo, "status", "--porcelain") == ""
+ assert _git(repo, "write-tree") == tree
+
+
+def test_check_fails_before_the_move_and_passes_after(repo, capsys):
+ argv = ["--from", OLD, "--to", NEW, "--root", str(repo), "--check"]
+ assert codemod.main(argv) == 1
+ assert "check failed" in capsys.readouterr().out
+
+ codemod.apply(repo, OLD, NEW)
+ _git(repo, "commit", "-q", "-m", "move")
+ assert codemod.main(argv) == 0
+
+ # A reference in the old spelling that slips in later is caught.
+ _write(repo, {"late.py": "from jarvis.core import branding\n"})
+ _git(repo, "add", "late.py")
+ assert codemod.main(argv) == 1
+ assert "late.py" in capsys.readouterr().out
+
+
+def test_a_branch_that_added_a_module_replays_the_same_run(repo):
+ _write(
+ repo,
+ {
+ "jarvis/extra/__init__.py": "",
+ "jarvis/extra/tool.py": "from jarvis.core import branding\n",
+ "docs/extra.md": "See `jarvis/extra/tool.py` and `jarvis.extra.tool`.\n",
+ },
+ )
+ _git(repo, "add", ".")
+ _git(repo, "commit", "-q", "-m", "branch work")
+
+ codemod.apply(repo, OLD, NEW)
+
+ assert _read(repo, "dodaios/extra/tool.py") == "from dodaios.core import branding\n"
+ assert _read(repo, "docs/extra.md") == "See `dodaios/extra/tool.py` and `dodaios.extra.tool`.\n"
+
+
+def test_leftover_caches_under_the_new_name_do_not_stop_the_move(repo):
+ """A checkout that has been at the new layout before keeps untracked
+ directories there; the move works around them."""
+ cache = repo / "dodaios" / "core" / "__pycache__"
+ cache.mkdir(parents=True)
+ (cache / "config.cpython-311.pyc").write_bytes(b"\0cache")
+
+ report = codemod.apply(repo, OLD, NEW)
+
+ assert not report.blocked
+ tracked = _tracked(repo)
+ assert {name for name in tracked if name.startswith("jarvis/")} == {"jarvis/__init__.py"}
+ assert {"dodaios/core/config.py", "dodaios/ui/web/launcher.py"} <= tracked
+ assert (cache / "config.cpython-311.pyc").is_file()
+ assert _git(repo, "diff", "--name-only") == ""
+
+
+def test_an_existing_target_blocks_the_run_instead_of_being_overwritten(repo, capsys):
+ _write(repo, {"dodaios/core/config.py": "print('already here')\n"})
+ assert codemod.main(["--from", OLD, "--to", NEW, "--root", str(repo)]) == 2
+ assert "the target already exists" in capsys.readouterr().out
+ assert _read(repo, "dodaios/core/config.py") == "print('already here')\n"
+ assert (repo / "jarvis/core/config.py").is_file()
+
+
[email protected](("old", "new"), [("app", "app"), ("app", "appx"), ("App", "core")])
+def test_names_that_could_not_be_replayed_are_refused(old, new):
+ with pytest.raises(ValueError):
+ codemod.Rewriter(old, new, [])
+
+
+# --------------------------------------------------------------------------- compatibility
+
+
+def _python(repo: Path, *args: str) -> subprocess.CompletedProcess[str]:
+ # -S: the synthetic packages need nothing but the standard library, and a
+ # developer's own editable install must not answer for them.
+ return subprocess.run(
+ [sys.executable, "-S", "-B", *args],
+ cwd=repo,
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ check=False,
+ creationflags=_NO_WINDOW,
+ )
+
+
+def test_old_imports_resolve_to_the_same_module_objects(repo):
+ codemod.apply(repo, OLD, NEW)
+ script = (
+ "import sys; sys.path.insert(0, '.')\n"
+ "import jarvis.core.branding as a\n"
+ "import dodaios.core.branding as b\n"
+ "assert a is b, 'two copies of one module'\n"
+ "a.STATE.append('x'); assert b.STATE == ['x']\n"
+ "from jarvis.core.config import load\n"
+ "import dodaios.core.config, dodaios, jarvis\n"
+ "assert load is dodaios.core.config.load\n"
+ "assert jarvis is dodaios and jarvis.__version__ == '1.2.3'\n"
+ "import jarvis.brain, dodaios.brain\n"
+ "assert sys.modules['jarvis.brain'] is sys.modules['dodaios.brain']\n"
+ "paths = [m.__file__ for n, m in sys.modules.items() if n.endswith('core.branding')]\n"
+ "assert len(set(paths)) == 1, paths\n"
+ "print('ok')\n"
+ )
+ result = _python(repo, "-c", script)
+ assert result.returncode == 0 and result.stdout.strip() == "ok", result.stderr
+
+
+def test_an_import_under_the_new_name_first_is_aliased_too(repo):
+ codemod.apply(repo, OLD, NEW)
+ script = (
+ "import sys; sys.path.insert(0, '.')\n"
+ "import dodaios.core.branding as b\n"
+ "import jarvis.core.branding as a\n"
+ "assert a is b\n"
+ "import importlib\n"
+ "try:\n"
+ " importlib.import_module('jarvis.core.missing')\n"
+ "except ModuleNotFoundError:\n"
+ " print('ok')\n"
+ )
+ result = _python(repo, "-c", script)
+ assert result.returncode == 0 and result.stdout.strip() == "ok", result.stderr
+
+
+ "module",
+ [
+ "jarvis",
+ "jarvis.ui.web.launcher",
+ "jarvis.ui.relauncher",
+ "jarvis.mcp.server",
+ "jarvis.mcp.agents.bridge",
+ ],
+)
+def test_old_start_commands_still_run(repo, module):
+ codemod.apply(repo, OLD, NEW)
+ result = _python(repo, "-m", module)
+ assert result.returncode == 0, result.stderr
+ expected = "jarvis.__main__" if module == "jarvis" else module
+ assert result.stdout.strip() == f"ran {expected} as __main__"
+
+
+def test_a_module_reached_by_its_old_name_keeps_its_own_spec(repo):
+ """The import system stamps the spec it loaded a module with on the
+ module; the real one must not end up described by the old name."""
+ codemod.apply(repo, OLD, NEW)
+ script = (
+ "import sys; sys.path.insert(0, '.')\n"
+ "import jarvis.core.branding as a\n"
+ "import jarvis.core as package\n"
+ "assert a.__name__ == a.__spec__.name == 'dodaios.core.branding', a.__spec__\n"
+ "assert package.__spec__.name == 'dodaios.core', package.__spec__\n"
+ "import importlib\n"
+ "assert importlib.reload(a) is sys.modules['jarvis.core.branding']\n"
+ "print('ok')\n"
+ )
+ result = _python(repo, "-c", script)
+ assert result.returncode == 0 and result.stdout.strip() == "ok", result.stderr
+
+
+def test_an_install_that_only_maps_the_old_directory_still_finds_the_package(repo, tmp_path):
+ """An editable install made before the move hands out the old directory
+ for the old name and knows nothing of the new one."""
+ codemod.apply(repo, OLD, NEW)
+ elsewhere = tmp_path / "elsewhere"
+ elsewhere.mkdir()
+ script = (
+ "import importlib.util, os, sys\n"
+ f"init = {str(repo / 'jarvis' / '__init__.py')!r}\n"
+ "assert importlib.util.find_spec('dodaios') is None\n"
+ "spec = importlib.util.spec_from_file_location(\n"
+ " 'jarvis', init, submodule_search_locations=[os.path.dirname(init)])\n"
+ "module = importlib.util.module_from_spec(spec)\n"
+ "sys.modules['jarvis'] = module\n"
+ "spec.loader.exec_module(module)\n"
+ "import jarvis, dodaios\n"
+ "from jarvis.core.config import load\n"
+ "assert jarvis is dodaios and load is dodaios.core.config.load\n"
+ "print('ok')\n"
+ )
+ # -I: neither the working directory nor PYTHONPATH may answer for it.
+ result = subprocess.run(
+ [sys.executable, "-I", "-S", "-B", "-c", script],
+ cwd=elsewhere,
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ check=False,
+ creationflags=_NO_WINDOW,
+ )
+ assert result.returncode == 0 and result.stdout.strip() == "ok", result.stderr
+
+
+def test_the_compatibility_package_carries_a_version_no_release_has(repo):
+ codemod.apply(repo, OLD, NEW)
+ stub = _read(repo, "jarvis/__init__.py")
+ assert f'__version__ = "{codemod.STUB_VERSION}"' in stub
+ assert '__version__ = "1.2.3"' in _read(repo, "dodaios/__init__.py")
+
+
+# --------------------------------------------------------------------------- this repository
+
+
+def test_no_workflow_filter_is_left_behind_on_the_old_directory():
+ """Every ``paths:`` filter, ``hashFiles`` and working directory in the
+ real workflows follows the package, so the move turns no lane off."""
+ rewriter = codemod.Rewriter.from_tree(_REPO_ROOT, OLD, NEW)
+ workflows = sorted((_REPO_ROOT / ".github" / "workflows").glob("*.yml"))
+ assert workflows
+ for workflow in workflows:
+ relative = workflow.relative_to(_REPO_ROOT).as_posix()
+ data, result = rewriter.rewrite(relative, workflow.read_bytes())
+ assert not result.ambiguous, [hit.render() for hit in result.ambiguous]
+ for number, line in enumerate(data.decode("utf-8").splitlines(), 1):
+ if codemod.KEEP_PRAGMA in line:
+ continue
+ for match in rewriter._token.finditer(line):
+ tail = line[match.end() : match.end() + 1]
+ head = line[match.start() - 1 : match.start()] if match.start() else ""
+ assert not (tail == "/" and head not in ("/", ".", "-", "_")), (
+ f"{relative}:{number}: {line.strip()}"
+ )