MooTool Next Compose 的 Git 仓库 pull 冲突期禁用机制:DIFF-624 切片实现与双层防线解析

原创2026-10-15 19:18:221,717 阅读
文章标签:开发工具桌面应用MCP 服务

MooTool Next Compose 的 Git 仓库 pull 冲突期禁用机制:DIFF-624 切片实现与双层防线解析

导读

本篇技术指南围绕 MooTool 桌面工具链 Compose 版本(next-compose)中 Vault Git 远程面板(A03) 的一个行为切片展开:当工作区存在未解决的合并冲突(conflicts > 0)时,界面上的 pull 按钮必须禁用。文章将完整剖析 DIFF-624 的实现范围、纯函数式的按钮启用判定逻辑、GitEngine.pull 引擎侧守卫,以及配套的单元测试、真实 Git 场景产品证据流与桌面截图证据帧(217)。读完你将掌握:冲突计数 conflicts 如何从 git status 解析而来、UI 与引擎两层防线的职责边界,以及为何 fetch 在冲突期保持可用而 pull 必须禁用。

DIFF-624 切片定位:完整冲突期操作矩阵的最后一环

DIFF-624 的基线是 DIFF-623(工作区),文档将这一改动明确归类为“A03 Vault Git 未解决冲突期 pull UI 禁用”,核心范围只有一句话:GitVaultRemotePresentation.pullEnabled / pullActionEnabled 在 conflicts > 0 时禁用 pull。但这句话背后是一套完整的“未解决冲突期操作矩阵”:

操作 merging=true(merge/rebase 进行中) conflicts>0 且 merging=false 相关切片
fetch ✅ 可用(仅要求 remote) ✅ 仍可用 DIFF-619
pull ❌ 禁用 ❌ 禁用(本切片补齐) DIFF-624
push ❌ 禁用 ❌ 禁用 DIFF-623
commit ❌ 禁用 ❌ 禁用(commitEnabled) DIFF-618

原文档特别强调“不重复 619/623”:DIFF-619 锁定的是“rebase 进行中 fetch 可用 + pull 因 merging=true 禁用”场景;DIFF-623 锁定的是“push + conflicts”;而本切片补齐的是 pull + conflicts 且 merging=false 的场景——即冲突计数存在、但当前并不处于一个活动的 merge/rebase 状态(例如曾经 abort 后遗留的未解决冲突、或非交互式合并遗留的 unmerged 路径)。这一切片落实了 DIFF-520 中“Pull 按钮要求 remote、非 merge/rebase 进行中且 conflicts == 0”的设计,并与 push/commit 的冲突期禁用策略保持一致。

冲突计数的来源:GitStatus.conflicts 如何从 git CLI 解析

理解 pull 禁用逻辑,首先要弄清 conflicts 数据从哪来。桌面端核心引擎 GitEngine.kt 定义了状态模型:

data class GitStatus(
    val available: Boolean,
    val repository: Boolean,
    val version: String = "",
    val branch: String = "",
    val remote: String = "",
    val ahead: Int = 0,
    val behind: Int = 0,
    val changes: List<GitChange> = emptyList(),
    val conflicts: Int = 0,
    val merging: Boolean = false,
    val operation: String = "none"
)

其中 conflicts 并不是直接读取 git 的某个输出字段,而是由 status 函数对 git status --porcelain 解析出的变更列表计数得到(GitEngine.kt):

GitStatus(
    ...
    changes = parsed.changes,
    conflicts = parsed.changes.count { it.conflict },
    merging = operation != "none",
    operation = operation
)

而单个变更的 conflict 布尔值,判定规则是 porcelain 双字符状态码:code.contains('U')(如 UU/DU/UD 等 unmerged 组合)或 AA、DD(双方同时新增/删除的目录冲突)(GitEngine.kt)。

val conflict = code.contains('U') || code == "AA" || code == "DD"
changes += GitChange(path, original?.ifBlank { null }, code, conflict)

这一设计意味着:只要 git status 中存在任一 unmerged 路径,conflicts 就大于 0,无论当前是否处于 merging 状态——这正是 DIFF-624 要覆盖的“有冲突计数但非 merging”场景的底层依据。

核心实现:pullEnabled 与 pullActionEnabled 的判定逻辑

本切片的主战场是纯函数对象 GitVaultRemotePresentation.kt,它负责 Vault Git 面板中所有与远程操作相关的按钮启停,并且源码注释明确它“对齐 Electron 只读 status.remote”:

fun pullEnabled(persistedRemote: String, merging: Boolean, conflicts: Int = 0): Boolean =
    GitOperationPresentation.pullEnabled(networkRemotePresent(persistedRemote), merging) &&
        conflicts == 0

fun pushEnabled(persistedRemote: String, merging: Boolean, conflicts: Int = 0): Boolean =
    GitOperationPresentation.pushEnabled(networkRemotePresent(persistedRemote), merging) &&
        conflicts == 0

fun pullActionEnabled(
    persistedRemote: String,
    merging: Boolean,
    busy: Boolean,
    conflicts: Int = 0,
): Boolean = !busy && pullEnabled(persistedRemote, merging, conflicts)

pullEnabled 是两层与运算的合成结果:

  1. 基础层来自 GitOperationPresentation.kt 的通用判定——要求 remote 已持久化且非 merge/rebase 进行中:
    fun pullEnabled(remotePresent: Boolean, merging: Boolean): Boolean =
        remotePresent && !merging
    
  2. 冲突层是 DIFF-624 新增的约束——conflicts == 0。

而 pullActionEnabled 进一步叠加 !busy(面板忙态禁用),这是 VaultGitDialog 所有工具栏按钮的统一约定。需要注意:pullEnabled 与 pushEnabled 在“未配置 remote”“merge 进行中”时的判定完全一致,只是冲突层在 DIFF-624 之前 push 已先行实现(DIFF-623),本切片为 pull 补齐了同一约束,使两者语义完全对称。

UI 调用点:VaultGitDialog 顶栏按钮如何消费该判定

纯函数判定最终在 VaultGitDialog.kt 的顶栏工具栏中被消费。Pull 按钮每次根据实时 GitStatus 计算可用性:

MooButton(
    container.t("git.pull"),
    p5Toolbar = true,
    enabled = GitVaultRemotePresentation.pullActionEnabled(
        status.remote,
        status.merging,
        busy,
        conflicts = status.conflicts,
    ),
    onClick = { runAction(workingTree = GitVaultFlushAction.Pull) { GitEngine.pull(root, token = token()) } },
)

同一区块中 fetch / push 按钮的调用形成了完整的对照:

  • fetch:fetchActionEnabled(status.remote, busy)——只要求 remote 与 !busy,不检查 merging 和 conflicts,即“冲突期仍可用”;
  • pull:pullActionEnabled(status.remote, status.merging, busy, conflicts = status.conflicts)——本切片新增的冲突约束在此生效;
  • push:pushActionEnabled(status.remote, status.merging, busy, conflicts = status.conflicts)——DIFF-623 已实现的对称约束。

面板在 runAction 成功后还会重新执行 GitEngine.status(root) 刷新 GitStatus,因此一旦冲突解决完毕,conflicts 归零,pull 按钮会自动恢复可用,无需手动刷新。

引擎侧防线:GitEngine.pull 的守卫优先级

UI 禁用只是第一道防线;即使绕过 UI 直接调用引擎,GitEngine.pull 也内置了同样的守卫,且冲突检查先于 remote 检查:

fun pull(root: Path, isolateConfig: Boolean = false, token: String = ""): GitActionResult = locked(root) {
    val current = status(root, isolateConfig)
    if (!current.repository) return@locked GitActionResult(false, "Git repository is not initialized")
    if (current.merging) return@locked GitActionResult(false, "Finish or abort the current merge/rebase before pulling")
    if (current.conflicts > 0) {
        return@locked GitActionResult(false, "Resolve all conflicts before pulling")
    }
    if (current.remote.isBlank()) return@locked GitActionResult(false, "No origin remote is configured")
    val result = run(listOf("pull", "--no-rebase", "origin"), root, isolateConfig, token, REMOTE_TIMEOUT_MS)
    ...
}

守卫顺序值得注意:先检查 merging,再检查 conflicts > 0,最后才检查 remote 是否存在。这对应了 GitPullGuardTest 中“merge 中拒绝优先于 missing-remote 提示”(mergeInProgressRejectedBeforeMissingRemoteMessage)以及“冲突未解决时 pull 被拒绝且提示包含 merge 字样”(pullBlockedWhileMergeConflictsRemain)两条用例的断言。命令实际执行的是 git pull --no-rebase origin,超时上限为 REMOTE_TIMEOUT_MS(120 秒,区别于本地命令的 30 秒)。GitEngine.push 采用了完全相同的三层守卫结构(repository → merging → conflicts),保证 UI 与引擎行为一致。

单元测试:pullDisabledWhileUnresolvedConflicts

本切片对应的核心单测位于 GitVaultRemotePresentationTest.kt 的 pullDisabledWhileUnresolvedConflicts,它是 DIFF-624 文档中明确点名的用例:

@Test
fun pullDisabledWhileUnresolvedConflicts() {
    val remote = "https://x.git"
    assertFalse(
        GitVaultRemotePresentation.pullActionEnabled(
            persistedRemote = remote,
            merging = false,
            busy = false,
            conflicts = 1,
        ),
    )
    assertTrue(
        GitVaultRemotePresentation.pullActionEnabled(
            persistedRemote = remote,
            merging = false,
            busy = false,
            conflicts = 0,
        ),
    )
}

测试特意使用 merging = false 与 conflicts = 1 的组合,精确锁定“有冲突计数但非 merge 进行中”这一 DIFF-624 独有场景(与 DIFF-619 的 merging=true 场景形成互补)。同一测试类还通过 fetchStaysEnabledDuringMergeWithConflicts 验证了冲突期间 fetch 保持可用、pull 被禁用的对照语义:

assertTrue(GitVaultRemotePresentation.fetchActionEnabled(remote, busy = false),
    "fetch stays enabled during merge/rebase conflicts (Electron VaultGitDialog)")
assertFalse(GitVaultRemotePresentation.pullActionEnabled(
    persistedRemote = remote, merging = true, busy = false, conflicts = 2))

产品证据流:真实 merge/rebase 场景中的 pull 断言

除了纯函数单测,DIFF-624 文档还要求“merge/rebase 产品证据流传入 conflicts”。这意味着在真实 Git 仓库中构造冲突,通过 GitEngine 走完整流程并断言 pull 的启停。以 GitMergeProductEvidenceFlowTest.kt 为例,测试用 GitEngine 在本地裸仓库 + upstream + clone 的三仓库拓扑中制造冲突(上游修改 evidence-conflict.json,本地修改同一文件后 GitEngine.pull 必然失败):

  • 冲突阶段(§B):status.conflicts >= 1,同时断言 pushActionEnabled、pullActionEnabled、commitActionEnabled 全部为 false,而 fetchActionEnabled 为 true,并执行真实的 GitEngine.fetch 确认成功;
  • 解决阶段:GitEngine.resolveConflict(..., "theirs") 后 status.conflicts == 0,mergeContinueActionEnabled 恢复为 true;
  • 完成阶段:continueOperation 结束后 operation == "none",pullActionEnabled / pushActionEnabled 重新恢复为 true(“pull re-enabled after merge completes”)。

GitRebaseProductEvidenceFlowTest.kt 对 rebase 场景重复了同样的断言流程,并显式注释“pull must stay disabled during rebase §C while conflicts remain”,证明该约束对 merge 与 rebase 两条冲突路径都成立。

证据帧 217:桌面截图捕获测试

DIFF-624 的验证不仅停留在断言层面,还要求产出可直观核对的 UI 证据帧。证据帧编号 217 由 GitVaultPullDisabledConflictsCaptureTest.kt 生成:

  • 使用 Compose 桌面 UI 测试框架 runDesktopComposeUiTest(width = 480, height = 120),在浅色 modern 主题下渲染一个真实的 MooButton;
  • 按钮文案来自中文 i18n(Translator(AppLanguage.ZhCN) 的 git.pull),enabled 直接传入:
    GitVaultRemotePresentation.pullActionEnabled(
        persistedRemote = "https://example.git/repo.git",
        merging = false,
        busy = false,
        conflicts = 2,
    )
    
  • 截图输出到 docs/evidence/2026-09-15-inspector-screencapture/windows/217-compose-git-pull-disabled-unresolved-conflicts-tab-focus.png,并断言文件非空(file.length() > 500)。

与 DIFF-623 的帧 216(GitVaultPushDisabledConflictsCaptureTest,同样 merging=false + conflicts=2)形成姊妹帧,两帧共同证明“未解决冲突、非 merge 进行中”时 pull 与 push 按钮均处于禁用态。整个“截图证据”体系由 product-evidence-common.sh 等脚本支撑,作为跨平台行为一致性的可读凭据。

验证命令与运行前提

按文档约定,本切片的全部验证依赖 JDK 21,在 next-compose 目录下执行:

./gradlew :composeApp:desktopTest --offline --no-daemon

其中 --offline 保证使用本地 Gradle 依赖缓存,--no-daemon 避免常驻守护进程干扰。涉及真实 git CLI 的测试(如 GitPullGuardTest、merge/rebase 产品证据流)会在 GitEngine.detect().available 为 false 时通过 JUnit Assume 自动跳过,因此即使测试机未安装 git,纯函数单测与 UI 捕获测试仍可正常执行。

小结

DIFF-624 看似只改动了几个布尔表达式,实则是 Vault Git 冲突期“UI 提示 → 纯函数判定 → 引擎守卫 → 截图证据”完整闭环的一部分。从 GitOperationPresentation 的基础约束、GitVaultRemotePresentation 的 conflicts == 0 增量,到 GitEngine 的 pull 守卫与 status 冲突解析,再到两处产品证据流与帧 216/217 截图,pull 与 push、commit 在冲突期行为完全对齐,而 fetch 始终作为“只读、无副作用”的操作保持可用——这正是未解决冲突期最安全的远程操作策略。

登录后查看全文
MooTool