Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

21.2 KB
Raw Blame
"""把 Dependabot 的清单升级接管到本地分支,顺手重算派生产物。默认只列计划,`--apply` 才提交。

Dependabot 只改 manifest 和 lock。根 `package.json` 的 npm 包还有一层派生产物——
`web/vendor/**` 的字节、`web/index.html` 里那行版本注释、每个 `ORIGIN.md` 的哈希与
lock integrity——它算不出来,于是 `npm run check:vendor` 在它的 PR 上必红(实际发生过:
lucide-static 1.38.0 → 1.40.0 的 PR #4)。`frontend/package.json` 同理,产物是
`web/dist/` 中的主界面与独立页面包。

修不了那个 PR 本身:Dependabot 触发的 workflow 拿到的 token 是只读的,往
`dependabot/**` 推回重算的产物得靠 `pull_request_target` 或一个 PAT,两条都是给 CI 加
提权面。所以接管在本地做——凭据是你自己的,CI 一行都不用改。

uv 与 github-actions 没有派生产物,也在这里接管:master 在本机集成、通常领先 origin,
在网页上合并会让两边分叉,回并又被 `scripts/githooks/` 拒收。

每个 PR 做完这些:

1. `git fetch` 它的 head 分支,把它对清单的改动三方合并套到当前分支;
2. 按清单重算派生产物(npm),或核对锁文件(uv);
3. 列出真实改动的文件,`--apply` 时只暂存这些并提交,一个 PR 一个提交。

`--all-open` 按编号从小到大接管全部 open 的 Dependabot PR。两个 PR 改到相邻行时三方
合并报冲突,脚本停在那个 PR,报出冲突文件并备好提交说明;解完冲突提交后再跑一次,
已经在 HEAD 上的升级会跳过。

测试不在这里跑:仓库只有一个测试入口,另拼一条会让 `test_evidence` 的记录对不上。
脚本最后印出该跑的命令与推送后收尾的 `gh pr close`。
"""
from __future__ import annotations

import argparse
import json
from pathlib import Path
import re
import shutil
import subprocess
import sys

if not __package__:
    sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
    __package__ = "scripts"
from . import co_author

ROOT = Path(__file__).resolve().parents[1]
DELIVERY_STEPS = [
    "提交后预检(工作树根目录,PowerShell 7):"
    "& .\\.venv\\Scripts\\python.exe -X utf8 .\\scripts\\agent_worktree.py preflight",
    "测试:& .\\scripts\\test.ps1 full",
    "交付:推送工作者分支并创建交付 PR,核对当前提交的 CI;ready 后由协调者 integrate",
]

#: 每份清单的接管方式。`manifests` 是从 Dependabot 分支套过来的文件,`derived` 是重算后
#: 可能变的路径,`commands` 是重算命令,`checks` 只核对不产出文件。以 `/` 结尾的条目按
#: 目录算,其余按整条路径比。
RECIPES = {
    "docker": {
        "label": "应用与工作流 Docker 镜像",
        "manifests": ("Dockerfile", ".github/actions/actionlint/Dockerfile", "compose.yaml"),
        "derived": (),
        "commands": (),
        "checks": (),
    },
    "web": {
        "label": "根 package.json(本地固定 web 依赖)",
        "manifests": ("package.json", "package-lock.json"),
        "derived": ("web/vendor/", "web/index.html", "web/dist/", "docs/REUSE.md",
                    "frontend/src/player/videojs.ts", "tests/test_web_ui.py",
                    "frontend/src/react/photo-lightbox/photo-lightbox.ts",
                    "frontend/test/react/photo-lightbox.test.tsx"),
        "commands": (("npm", "ci", "--ignore-scripts"), ("npm", "run", "vendor:web"),
                     ("npm", "--prefix", "frontend", "ci"),
                     ("npm", "--prefix", "frontend", "run", "build")),
        "checks": (),
    },
    "frontend": {
        "label": "frontend/package.json(island 层构建依赖)",
        "manifests": ("frontend/package.json", "frontend/package-lock.json"),
        "derived": ("web/dist/",),
        "commands": (("npm", "--prefix", "frontend", "ci"),
                     ("npm", "--prefix", "frontend", "run", "build")),
        "checks": (),
    },
    "uv": {
        "label": "Python 依赖(pyproject.toml 与 uv.lock)",
        "manifests": ("pyproject.toml", "uv.lock"),
        "derived": (),
        "commands": (),
        "checks": (("uv", "lock", "--check"),),
    },
    "amane": {
        "label": "amane 桥的独立 Python 依赖",
        "manifests": ("tools/amane-bridge/pyproject.toml", "tools/amane-bridge/uv.lock"),
        "derived": (),
        "commands": (),
        "checks": (("uv", "lock", "--project", "tools/amane-bridge", "--check"),),
    },
    "actions": {
        "label": "GitHub Actions 工作流",
        "manifests": (".github/workflows/",),
        "derived": (),
        "commands": (),
        "checks": (),
    },
}

#: 推送后关 PR 时的留言,按有没有派生产物分两种说法。
CLOSE_COMMENT = {
    True: "派生产物需要本地重算,已在工作树接管进 master",
    False: "本地 master 领先 origin,网页合并会让两边分叉,已在工作树接管进 master",
}


class ConflictError(RuntimeError):
    """三方合并留下了冲突,`files` 是冲突文件。"""

    def __init__(self, message: str, files: list[str]):
        super().__init__(message)
        self.files = files


def run(command: tuple[str, ...] | list[str], *, capture: bool = True,
        root: Path = ROOT) -> str:
    """在仓库根目录跑一条命令,失败即抛。

    第一个词过一遍 `shutil.which`:Windows 上 `npm` 是 `npm.cmd`,而 `CreateProcess`
    不查 `PATHEXT`,照字面传就是 FileNotFoundError。
    """
    executable = shutil.which(command[0]) or command[0]
    result = subprocess.run([executable, *command[1:]], cwd=root, capture_output=capture,
                            text=True, encoding="utf-8", errors="replace", check=False)
    if result.returncode != 0:
        detail = (result.stderr or result.stdout or "").strip() if capture else ""
        raise RuntimeError(f"{' '.join(command)} 退出码 {result.returncode}\n{detail}")
    return (result.stdout or "") if capture else ""


def matches(entry: str, path: str) -> bool:
    return path.startswith(entry) if entry.endswith("/") else path == entry


def recipe_for(paths: list[str]) -> tuple[str, dict]:
    """一批改动文件属于哪份清单。

    同时动了两份就拒绝:那不是 Dependabot 的形状(一个 PR 只碰一个 ecosystem 的一个
    directory),硬按一份重算会把另一份的产物留在旧版本上。清单之外的文件也拒绝:
    认不出来的改动不替人决定怎么接。
    """
    matched = [key for key, recipe in RECIPES.items()
               if any(matches(entry, path) for entry in recipe["manifests"] for path in paths)]
    if not matched:
        known = "、".join(entry for recipe in RECIPES.values() for entry in recipe["manifests"])
        raise RuntimeError(f"这个分支没有改动认得的清单(认得的是 {known})")
    if len(matched) > 1:
        raise RuntimeError(f"这个分支同时改了 {len(matched)} 份清单,逐份接管:{matched}")
    recipe = RECIPES[matched[0]]
    stray = [path for path in paths if not any(matches(entry, path) for entry in recipe["manifests"])]
    if stray:
        raise RuntimeError(f"这个分支改了清单之外的文件:{stray}")
    return matched[0], recipe


def open_pull_requests() -> list[dict]:
    """全部 open 的 Dependabot PR,按编号从小到大。"""
    payload = json.loads(run(("gh", "pr", "list", "--state", "open", "--author", "app/dependabot",
                              "--limit", "100", "--json", "number,title,headRefName")))
    return sorted(payload, key=lambda item: item["number"])


def pull_request(pr: str) -> dict:
    payload = json.loads(run(("gh", "pr", "view", pr, "--json", "number,title,headRefName,state")))
    if payload["state"] != "OPEN":
        raise RuntimeError(f"PR #{pr} 状态是 {payload['state']},不是 OPEN")
    return payload


def fetch(branch: str, *, root: Path = ROOT) -> None:
    run(("git", "fetch", "--quiet", "origin", branch), root=root)


def branch_changes(branch: str, *, root: Path = ROOT) -> list[str]:
    """那个分支自己改了哪些文件。

    判据是它与 `HEAD` 的合并基,不是 `HEAD` 本身:Dependabot 的分支从几天前的 master
    分出去,直接 `git diff origin/<branch>` 会把这几天 master 上的每一次改动也算进来,
    于是每个 PR 看上去都动了清单。
    """
    return [line for line in
            run(("git", "diff", "--name-only", "--merge-base", "HEAD", f"origin/{branch}"),
                root=root).splitlines()
            if line]


def bring_over(branch: str, manifests: tuple[str, ...], *, root: Path = ROOT,
               refresh: bool = True) -> None:
    """取回那个分支,把它对清单的改动套到工作区,不暂存。

    套的是它自合并基以来的 diff,不是整份文件:分支的清单停在几天前的 master 上,
    整份签出会把这几天 master 往清单里加的依赖一并抹掉(实际发生过:#20 的
    `frontend/package.json` 没有后来加进来的 `sonner`)。两边改到同一行或相邻行时
    `--3way` 留下冲突,抛 `ConflictError` 报出文件,不替人挑一边。补丁先落成文件再给
    `git apply`:Windows 上文本模式的 stdin 会把 `\\n` 写成 `\\r\\n`,补丁就对不上了。
    `--3way` 要求工作区与暂存区一致,连着套几个分支时,每套一个先暂存再套下一个。
    刚 fetch 过的调用方传 `refresh=False`。
    """
    if refresh:
        fetch(branch, root=root)
    patch = run(("git", "diff", "--merge-base", "HEAD", f"origin/{branch}", "--", *manifests),
                root=root)
    if not patch:
        return
    path = root / "build" / "adopt.patch"
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(patch, encoding="utf-8", newline="\n")
    try:
        run(("git", "apply", "--3way", str(path)), root=root)
    except RuntimeError as exc:
        conflicts = [line for line in
                     run(("git", "diff", "--name-only", "--diff-filter=U"), root=root).splitlines()
                     if line]
        if conflicts:
            raise ConflictError(f"origin/{branch} 与当前分支改到同一处,三方合并留下冲突",
                                conflicts) from exc
        raise
    finally:
        path.unlink()
    run(("git", "reset", "--quiet", "--", *manifests), root=root)


def working_changes(*, root: Path = ROOT) -> list[str]:
    tracked = run(("git", "diff", "--name-only", "HEAD"), root=root).splitlines()
    added = run(("git", "ls-files", "--others", "--exclude-standard"), root=root).splitlines()
    return sorted({line for line in (*tracked, *added) if line})


def commit_message(key: str, versions: list[str], pr: str | None,
                   signature: str) -> str:
    """生成依赖接管提交的来源、重算步骤与署名。

    署名由 `--co-author` 传进来,脚本不替谁署名:跑它的可能是任一个智能体,写死一个
    工具名就是往提交历史里记错人。形态由 `co_author.FORM` 判,这里提前判一次,免得
    错在 `ready` 才报出来。
    """
    if co_author.FORM.fullmatch(signature) is None:
        raise ValueError("--co-author 形态须为 工具 (模型 版本) <厂商 noreply>,如 "
                         + co_author.EXAMPLE.partition(": ")[2])
    recipe = RECIPES[key]
    origin = f"Dependabot PR #{pr}" if pr else "Dependabot 分支"
    if recipe["commands"]:
        rebuild = "`" + "`、`".join(" ".join(item) for item in recipe["commands"]) + "`"
        why = (f"{origin} 只改了 manifest 与 lock。派生产物由 {rebuild} 重算,"
               "它在只读 token 下算不出来,所以接管到本地分支一起提交。")
    else:
        why = (f"{origin} 没有派生产物。本地 master 领先 origin 时在网页上合并会让两边分叉,"
               "所以接管到本地分支。")
    return (f"chore(deps): 接管 {recipe['label']} 的升级\n\n{why}\n\n"
            + ("升级:" + "、".join(versions) + "\n\n" if versions else "")
            + (f"Refs #{pr}\n\n" if pr else "")
            + f"Co-Authored-By: {signature}\n")


def manifest_versions(key: str, *, root: Path = ROOT) -> list[str]:
    """从套过来的清单里读出被改掉的版本,只为写进提交说明。"""
    lines = []
    for name in RECIPES[key]["manifests"]:
        if not name.endswith("package.json"):
            continue
        before = json.loads(run(("git", "show", f"HEAD:{name}"), root=root) or "{}")
        after = json.loads((root / name).read_text(encoding="utf-8"))
        for section in ("dependencies", "devDependencies"):
            old, new = before.get(section, {}), after.get(section, {})
            lines += [f"{package} {old.get(package, '新增')} → {version}"
                      for package, version in new.items() if old.get(package) != version]
    return lines


def owned_by(recipe: dict, path: str) -> bool:
    """这个路径是不是本次接管该动的:清单本身或它的派生产物。"""
    return any(matches(entry, path) for entry in (*recipe["manifests"], *recipe["derived"]))


def close_command(pr: int, key: str) -> str:
    comment = CLOSE_COMMENT[bool(RECIPES[key]["commands"])]
    return f'gh pr close {pr} --delete-branch --comment "{comment}"'


def adopted(number: int, branch: str, *, root: Path = ROOT) -> bool:
    """那个分支分叉之后,HEAD 上有没有提交说明写着接管了这个 PR。

    不拿三方合并的结果判:上一轮停在冲突、人解完提交后,前面那些 PR 再套一次会跟解冲突
    留下的相邻行再撞一次,「已接管的跳过」就成了「再停一次」。
    """
    base = run(("git", "merge-base", "HEAD", f"origin/{branch}"), root=root).strip()
    log = run(("git", "log", "--format=%B", f"{base}..HEAD"), root=root)
    return re.search(rf"^Dependabot PR #{number}(?!\d) (?:只改了 manifest 与 lock|没有派生产物)",
                     log, re.M) is not None


def adopt(pr: dict, *, apply: bool, signature: str, root: Path = ROOT) -> dict:
    """接管一个 PR。`apply` 时暂存并提交;否则改动留在工作区未暂存。

    升级已经在 HEAD 上(上次停在冲突、解完提交后再跑)时什么都不做,报 `already`。
    """
    branch, number = pr["headRefName"], pr.get("number")
    fetch(branch, root=root)
    key, recipe = recipe_for(branch_changes(branch, root=root))
    result = {"pr": number, "branch": branch, "recipe": key}
    if number and adopted(number, branch, root=root):
        return {**result, "already": True}
    bring_over(branch, recipe["manifests"], root=root, refresh=False)
    if not working_changes(root=root):
        return {**result, "already": True}
    versions = manifest_versions(key, root=root) or ([pr["title"]] if pr.get("title") else [])
    for command in recipe["commands"]:
        run(command, capture=False, root=root)
    for command in recipe["checks"]:
        run(command, root=root)
    # 只认真实变了的那些。清单动了产物却一个字节没变是常事(补丁版没碰 vendored 的
    # 那几个文件),照 `derived` 前缀盲暂存会把无关文件带上。
    touched = working_changes(root=root)
    landed = sorted(path for path in touched if owned_by(recipe, path))
    stray = sorted(path for path in touched if not owned_by(recipe, path))
    result.update(versions=versions, files=landed, unexpected=stray, applied=False)
    if stray:
        raise RuntimeError(f"PR #{number} 重算动到了清单与派生产物之外的文件,先看清楚:{stray}")
    if apply:
        run(("git", "add", "--", *landed), root=root)
        message = root / "build" / f"adopt-{key}.txt"
        message.parent.mkdir(parents=True, exist_ok=True)
        message.write_text(commit_message(key, versions, number and str(number), signature),
                           encoding="utf-8", newline="\n")
        run(("git", "commit", "--quiet", "-F", str(message)), root=root)
        message.unlink()
        result.update(applied=True, head=run(("git", "rev-parse", "HEAD"), root=root).strip())
    return result


def adopt_all(prs: list[dict], *, signature: str, root: Path = ROOT) -> dict:
    """逐个接管并提交;停在第一个冲突或失败的 PR,已提交的留着。"""
    commit_message("uv", [], None, signature)  # 署名写错就一个都别动
    done: list[dict] = []
    for pr in prs:
        try:
            done.append(adopt(pr, apply=True, signature=signature, root=root))
        except ConflictError as exc:
            key, recipe = recipe_for(branch_changes(pr["headRefName"], root=root))
            message = root / "build" / f"adopt-pr-{pr['number']}.txt"
            message.write_text(commit_message(key, [pr["title"]], str(pr["number"]), signature),
                               encoding="utf-8", newline="\n")
            rebuild = [" ".join(command) for command in (*recipe["commands"], *recipe["checks"])]
            return {"ok": False, "error": str(exc), "stopped_at": pr["number"],
                    "conflicts": exc.files, "done": done,
                    "next": [f"解开冲突:{'、'.join(exc.files)}",
                             *(f"重算或核对:{command}" for command in rebuild),
                             f"git add -- {' '.join(exc.files)}"
                             + (",连同重算改到的派生产物(看 git status)" if recipe["commands"] else ""),
                             f"git commit -F {message.relative_to(root).as_posix()}",
                             "再跑一次 --all-open --apply,已接管的会跳过"]}
        except RuntimeError as exc:
            return {"ok": False, "error": str(exc), "stopped_at": pr["number"], "done": done}
    next_steps = [*DELIVERY_STEPS,
                  "推送 master 之后逐个收尾:",
                  *(close_command(item["pr"], item["recipe"]) for item in done)]
    return {"ok": True, "done": done, "next": next_steps if done else []}


def plan_all(prs: list[dict], *, root: Path = ROOT) -> dict:
    """只列要接管的 PR 与各自的清单,不动工作区。"""
    items = []
    for pr in prs:
        fetch(pr["headRefName"], root=root)
        paths = branch_changes(pr["headRefName"], root=root)
        try:
            key, _ = recipe_for(paths)
            items.append({"pr": pr["number"], "title": pr["title"], "recipe": key, "files": paths})
        except RuntimeError as exc:
            items.append({"pr": pr["number"], "title": pr["title"], "files": paths,
                          "error": str(exc)})
    return {"ok": all("error" not in item for item in items), "prs": items,
            "next": ["加 --apply 逐个接管并提交"] if items else []}


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    source = parser.add_mutually_exclusive_group(required=True)
    source.add_argument("--pr", help="Dependabot 的 PR 编号")
    source.add_argument("--branch", help="Dependabot 的分支名,跳过 gh 查询")
    source.add_argument("--all-open", action="store_true",
                        help="按编号从小到大接管全部 open 的 Dependabot PR")
    parser.add_argument("--apply", action="store_true", help="暂存并提交;缺省只列计划")
    parser.add_argument("--co-author", required=True,
                        help="本次提交的署名,形如 "
                             "Claude Code (Opus 5) <[email protected]>")
    args = parser.parse_args(argv)

    try:
        if run(("git", "rev-parse", "--git-dir")).strip() == run(("git", "rev-parse", "--git-common-dir")).strip():
            raise RuntimeError("这是主检出。主检出只做集成,先 "
                               "`scripts/agent_worktree.py create --agent <名> --task deps-<包名>`。")
        if run(("git", "status", "--porcelain")).strip():
            raise RuntimeError("工作区不干净。接管会往里写重算出来的产物,先把手上的改动收掉。")
        if args.all_open:
            prs = open_pull_requests()
            plan = (adopt_all(prs, signature=args.co_author) if args.apply else plan_all(prs))
        else:
            pr = pull_request(args.pr) if args.pr else {"headRefName": args.branch}
            item = adopt(pr, apply=args.apply, signature=args.co_author)
            plan = {"ok": True, **item,
                    "next": list(DELIVERY_STEPS)}
            if item.get("already"):
                plan["next"] = []
            elif not args.apply:
                plan["next"].insert(0, "改动留在工作区未暂存:"
                                       f"`git restore -- {' '.join(item['files'])}` 撤销,加 --apply 提交")
            elif args.pr:
                plan["next"].append("推送 master 之后收尾:" + close_command(item["pr"], item["recipe"]))
        print(json.dumps(plan, ensure_ascii=False, indent=2))
        return 0 if plan["ok"] else 1
    except ConflictError as exc:
        print(json.dumps({"ok": False, "error": str(exc), "conflicts": exc.files},
                         ensure_ascii=False, indent=2))
        return 1
    except (RuntimeError, OSError, ValueError, KeyError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False, indent=2))
        return 1


if __name__ == "__main__":
    raise SystemExit(main())