ISEP/hooks/lib/checkout_target_dir.py

#!/usr/bin/env python3
"""解出一條指令裡的 `git checkout` / `git switch` **真正會落在哪個目錄**。

管什麼
  line-needs-own-worktree.sh 要回答「這次切分支動的是哪個 repo」。舊版拿
  payload 的 `cwd` 當答案，於是 `cd <別的 repo> && git checkout <分支>` 這個
  形狀會**認錯 repo**（inkstone/ISEP#109 → comment 5398 實測）：

      指令：cd .../matrix/arcrun && git checkout fix/library-lifecycle-187
      舊版訊息：目錄：.../InkStoneCo   它現在在：feat/ticket-bell-webhook
                          ↑ 動的是 matrix/arcrun，講的卻是 InkStoneCo

  🔴 擋是擋對了，但**印給人的補救指令是另一個 repo 的**——照著做會在
  InkStoneCo 開一份用不到的 worktree，真正要隔離的 matrix/arcrun 沒開到，
  而人以為自己隔離好了。**一道閘給錯下一步，比不擋更糟。**
  而 `cd X && git checkout` 正是這條線最常出現的寫法（本票的來由那次就是它）。

為什麼接既有的解析器，不另寫一支
  `push_target_dir.py` 2026-08-23 已經替 `git push` 解過同一個問題
  （inkstone/ISEP#30 comment 3949），連多層 cd 鏈與**子殼的 cd 不外洩**
  （`(cd A && …); git checkout` 落在殼外而不是 A）都算過了。
  ⇒ 本檔只加「哪個動詞」與「哪些形狀不動 HEAD」，tokenize 與路徑接合一律沿用
  那支，不養第二套會漂的 parser。那支的 42 條既有測試在本次改動後全數重跑通過。

回傳三種，呼叫端要分開處理
  ""   這條指令裡沒有會**移動 HEAD** 的 checkout/switch ⇒ 不關這道閘的事
  "?"  有，但目錄**解不出來**（`cd $VAR`、`cd -`、引號壞掉）
       ⇒ 🔴 呼叫端必須放行。寧可漏擋，也不要指著錯的 repo 叫人去開 worktree
         ——那正是本檔要修的病，猜一個回去等於原地打轉。
  其他 目錄運算式，可能是相對的；呼叫端自己 `cd` 進去問 git（唯讀）。
       "." ＝「就是呼叫端自己的 cwd」（指令裡沒有 cd 也沒有 -C）。

出路的判準也住在這裡（inkstone/ISEP#109 → comment 6587，2026-09-07）
  閘訊息教的出路是 `WORKTREE_OK=1 git -C … checkout …`。舊版讀的是 **hook 自己的
  環境變數**，而 PreToolUse hook 跑在指令之前、跟指令不是同一個行程——指令字串裡的
  `WORKTREE_OK=1` 是給 git 的前綴賦值，hook 的行程裡根本沒有它 ⇒ 總管三次照貼三次被擋。
  ⇒ 改成認**指令字串裡的字面前綴**，而且判準是位置不是字：那個賦值必須是
  「會移動 HEAD 的那條 git 指令」自己的前綴（`echo WORKTREE_OK=1; git checkout` 不算、
  `WORKTREE_OK=1 echo hi && git checkout` 不算、寫在 commit 訊息裡不算）。
  留痕就是那個前綴本身——它在指令歷史上。

用法：printf '%s' "$CMD" | python3 checkout_target_dir.py                 → 目錄運算式（見上）
      printf '%s' "$CMD" | python3 checkout_target_dir.py --escape WORKTREE_OK=1
                                                                            → 那條 checkout 帶著這個前綴就印 1，否則空
"""
import os
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from push_target_dir import _ENV_ASSIGN, _events, _join  # noqa: E402

VERBS = ("checkout", "switch")
UNKNOWN = "?"


def _step(base, path):
    """走一步 cd／-C。不確定就一路標 unknown，不要往回猜成呼叫端的 cwd。"""
    if base == UNKNOWN:
        return UNKNOWN
    if not path or path == "-" or path.startswith("$") or path.startswith("`"):
        return UNKNOWN
    return _join(base, path)


def _moves_head(tokens):
    """tokens 是整串 `[NAME=value …] git …`。
    回傳 (會不會動 HEAD, -C 指的路徑 or None, 前綴賦值清單)。

    判準只有「這個動作動不動 HEAD」，不看任何措辭：
      git checkout -- <檔>／git checkout HEAD -- <檔>  ⇒ 還原檔案，不動
      git checkout -p                                  ⇒ 挑 hunk，不動
      git checkout（沒有任何目標）                      ⇒ git 自己會報錯
    """
    tok = list(tokens)
    env = []
    while tok and _ENV_ASSIGN.match(tok[0]):
        env.append(tok.pop(0))      # `WORKTREE_OK=1 git …` 的前綴——出路就認這個
    tok = tok[1:]                   # 去掉 "git"
    c_path = None
    while tok and tok[0].startswith("-"):
        if tok[0] == "-C" and len(tok) > 1:
            c_path = tok[1] if c_path is None else c_path + "/" + tok[1]
            tok = tok[2:]
            continue
        if tok[0].startswith("-C") and len(tok[0]) > 2:
            seg = tok[0][2:]
            c_path = seg if c_path is None else c_path + "/" + seg
            tok.pop(0)
            continue
        if tok[0].startswith("--git-dir"):
            return (False, None, env)   # 自己指 git-dir 的花式用法，不猜
        tok.pop(0)
    if not tok or tok[0] not in VERBS:
        return (False, None, env)

    rest = tok[1:]
    if "--" in rest or "-p" in rest or "--patch" in rest:
        return (False, None, env)
    if not [a for a in rest if not a.startswith("-")] and \
       not any(a in ("-b", "-B", "-c", "-C") for a in rest):
        return (False, None, env)
    return (True, c_path, env)


def find_checkout(cmd):
    """回 (目錄運算式, 那條 checkout 的前綴賦值清單)。目錄運算式的三種值見檔頭。"""
    events = _events(cmd, VERBS, strip_env=True)
    if not events:
        return ("", [])             # 引號壞掉之類——沿用「不擋在不確定上」

    stack = [None]                  # 每層括號各自的 cwd；None ＝ 同呼叫端的 cwd
    for kind, val in events:
        if kind == "enter":
            stack.append(stack[-1])          # 子殼繼承「進去那一刻」的位置
        elif kind == "exit":
            if len(stack) > 1:
                stack.pop()                  # 子殼自己 cd 到哪，出來不算數
        elif kind == "cd":
            stack[-1] = _step(stack[-1], val)
        elif kind == "verb":
            moves, c_path, env = _moves_head(val)
            if not moves:
                continue
            where = stack[-1]
            if c_path is not None:
                # -C 贏過 cd：git 自己就是這個優先序
                # （而且 -C 若是相對路徑，是接在 cd 之後算，不是接在 cwd）
                where = _step(where, c_path)
            if where == UNKNOWN:
                return (UNKNOWN, env)
            return (where or ".", env)
    return ("", [])


def find_checkout_target(cmd):
    return find_checkout(cmd)[0]


def has_escape(cmd, assignment):
    """會移動 HEAD 的那條 git 指令，自己的前綴裡有沒有這個字面賦值（例 `WORKTREE_OK=1`）。
    只看**那條指令的前綴**：印在別處、掛在別的指令上、寫在引號裡都不算。"""
    _expr, env = find_checkout(cmd)
    return assignment in env


def main():
    argv = sys.argv[1:]
    cmd = sys.stdin.read()
    if len(argv) == 2 and argv[0] == "--escape":
        sys.stdout.write("1" if has_escape(cmd, argv[1]) else "")
        return
    sys.stdout.write(find_checkout_target(cmd))


if __name__ == "__main__":
    main()