Files
LN-Code-Editor/lib/utils/git_error_mapper.dart
T
2026-09-19 21:07:45 +08:00

513 lines
18 KiB
Dart
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import '../l10n/app_localizations.dart';
/// Git 云端操作错误分类
///
/// 用于把底层 git 的英文 stderr 归类为可操作的错误类型,并驱动
/// 「一键修复」(如 push 被拒 → 先 Pull)与「去修账号」的按钮显隐。
///
/// 本类**不产生任何面向用户的文案**:所有 message / suggestion 均由 UI 层
/// 通过 [AppLocalizations] 按 [kind] 取词,从而保持与项目其余部分一致的
/// 中英双语能力(见 [GitErrorMapper.describe])。
enum GitOperationErrorKind {
/// 非 Git 错误(tarball/success 等)
none,
/// 令牌无效或已过期(HTTP 401)
authFailed,
/// 账号对该仓库没有写权限(HTTP 403,典型为推送别人的上游仓库)
writePermissionDenied,
/// 目标仓库不存在,或当前账号无权访问(HTTP 404)
repositoryNotFound,
/// 需要代理认证(HTTP 407)
proxyAuthRequired,
/// 请求被服务器拒绝,通常是推送内容或引用不合法(HTTP 422)
requestRejected,
/// 触发平台速率限制(HTTP 429)
rateLimited,
/// 其他被服务端拒绝的 HTTP 状态码
httpError,
/// 使用账号密码而非 PAT 访问 GitHub 等平台
passwordAuthDisabled,
/// 域名无法解析 / 网络不可达
networkUnreachable,
/// SSH 公钥未被平台接受
sshPublicKeyDenied,
/// SSH 私钥文件权限或缺失
sshKeyUnusable,
/// 首次连接未知主机,主机指纹未确认
hostKeyUnverified,
/// 推送被拒(远端有新提交,non-fast-forward)
nonFastForward,
/// force-with-lease 校验失败(远端已被他人更新)
staleForcePush,
/// rebase/merge 冲突
conflictDetected,
/// 本地有未提交改动,阻止了操作
localChangesWouldBeOverwritten,
/// 未设置上游追踪分支
noUpstreamConfigured,
/// 无法获取本地/远端引用锁(.git 被占用)
refLockFailed,
/// 磁盘空间不足
outOfSpace,
/// 命令超时
timeout,
/// 操作未完成,且输出里没有任何真实错误信息
operationIncomplete,
/// 其他未归类错误
unknown,
}
/// 错误可供用户执行的修复动作
enum GitErrorFixAction {
/// 先拉取(rebase)再推送
pullThenPush,
/// 重新抓取远端状态后重试
fetchAndRetry,
/// 放弃本次变基
abortRebase,
/// 前往 Git 账号管理
openAccountManagement,
/// 提示用户先 Fork(在提示文案中说明,无需按钮动作)
none,
}
/// 单条 Git 错误的**结构化**描述(不含任何本地化文案)
class GitErrorInfo {
final GitOperationErrorKind kind;
/// 兜底情况下从原始输出中提取的一条真实错误行(英文原文,直接展示)
final String? rawDetail;
/// 建议用户执行的修复动作(由 UI 渲染成按钮)
final GitErrorFixAction fixAction;
const GitErrorInfo({
required this.kind,
this.rawDetail,
this.fixAction = GitErrorFixAction.none,
});
/// 是否应提供「去修账号」入口
bool get needsAccountFix =>
fixAction == GitErrorFixAction.openAccountManagement;
/// 是否可通过「先 Pull 再 Push」自动修复
bool get canPullThenPush => fixAction == GitErrorFixAction.pullThenPush;
/// 是否可通过重新 fetch 后重试修复
bool get canRefreshThenRetry => fixAction == GitErrorFixAction.fetchAndRetry;
/// 该错误是否值得给出修复动作按钮
bool get hasFixAction => fixAction != GitErrorFixAction.none;
@override
String toString() => 'GitErrorInfo($kind, fix=${fixAction.name})';
}
/// 将 git stderr/stdout 归类为可操作的错误类型
class GitErrorMapper {
GitErrorMapper._();
/// 需要检查冲突的关键字(统一小写,与转小写后的输出比对)
static const List<String> conflictMarkers = [
'conflict',
'automatic merge failed',
'could not apply',
'failed to merge',
'fix conflicts',
'needs merge',
];
/// 解析命令输出,返回最贴合的错误分类
///
/// [stderr] 优先;[stdout] 在 stderr 为空时兜底(git 部分提示走 stdout)。
/// 返回结果不含本地化文案,由 UI 层按 [GitErrorInfo.kind] 取词。
static GitErrorInfo describe(String stderr, {String stdout = ''}) {
final raw = stderr.trim().isNotEmpty ? stderr : stdout;
final text = raw.toLowerCase();
if (text.trim().isEmpty) {
return const GitErrorInfo(kind: GitOperationErrorKind.operationIncomplete);
}
// ---- 1. 强推租约失败(必须先于通用 non-fast-forward 判断)----
if (text.contains('stale info') ||
(text.contains('force-with-lease') && text.contains('rejected'))) {
return const GitErrorInfo(
kind: GitOperationErrorKind.staleForcePush,
fixAction: GitErrorFixAction.fetchAndRetry,
);
}
// ---- 2. 认证与权限相关(按 HTTP 状态码细分,避免归因错误)----
// 2a. 平台已禁用密码认证
// 典型文案:`remote: Support for password authentication was removed on August 13, 2021.`
if (text.contains('support for password authentication was removed') ||
text.contains('password authentication was removed') ||
text.contains('password authentication is not')) {
return const GitErrorInfo(
kind: GitOperationErrorKind.passwordAuthDisabled,
fixAction: GitErrorFixAction.openAccountManagement,
);
}
// 2b. HTTP 401:凭证本身无效
if (text.contains('401') ||
text.contains('authentication failed') ||
text.contains('invalid username or password') ||
text.contains('could not read username') ||
text.contains('permission denied, please try again') ||
(text.contains('token') && text.contains('expired'))) {
return const GitErrorInfo(
kind: GitOperationErrorKind.authFailed,
fixAction: GitErrorFixAction.openAccountManagement,
);
}
// 2c. HTTP 403 / 明确的无写权限拒绝
// 最常见场景:origin 直接指向别人的上游仓库(如 ggml-org/llama.cpp)。
// 读取公开仓库不需要认证,因此拦截发生在推送时——此时令牌通常是好的。
if (text.contains('403') ||
(text.contains('permission to') && text.contains('denied')) ||
text.contains('write access') ||
text.contains('you do not have permission') ||
text.contains('protected branch')) {
return const GitErrorInfo(
kind: GitOperationErrorKind.writePermissionDenied,
fixAction: GitErrorFixAction.openAccountManagement,
);
}
// 2d. HTTP 407:代理需要认证
if (text.contains('407') || text.contains('proxy authentication required')) {
return const GitErrorInfo(kind: GitOperationErrorKind.proxyAuthRequired);
}
// 2e. HTTP 429:速率限制
if (text.contains('429') || text.contains('rate limit')) {
return const GitErrorInfo(kind: GitOperationErrorKind.rateLimited);
}
// 2f. HTTP 422:推送内容被服务器拒绝
if (text.contains('422')) {
return const GitErrorInfo(kind: GitOperationErrorKind.requestRejected);
}
// 2h. 仓库不存在 / 无权访问(HTTP 404 或 GitHub 文案)
if (text.contains('repository not found') ||
text.contains('does not appear to be a git repository') ||
text.contains('404')) {
return const GitErrorInfo(
kind: GitOperationErrorKind.repositoryNotFound,
fixAction: GitErrorFixAction.openAccountManagement,
);
}
// 2i. 其他 HTTP 状态码(兜底,必须放在所有具体状态码判断之后)
// 保留具体码值,不做统一归并,便于按状态码精确排查。
final httpMatch = RegExp(r'returned error:\s*(\d{3})').firstMatch(text);
if (httpMatch != null) {
return GitErrorInfo(
kind: GitOperationErrorKind.httpError,
rawDetail: httpMatch.group(1),
);
}
// ---- 3. SSH 主机指纹未确认 ----
if (text.contains('host key verification failed') ||
text.contains('remote host identification has changed')) {
return const GitErrorInfo(kind: GitOperationErrorKind.hostKeyUnverified);
}
// ---- 4. SSH 密钥类 ----
if (text.contains('permission denied (publickey)') ||
text.contains('no supported authentication methods')) {
return const GitErrorInfo(
kind: GitOperationErrorKind.sshPublicKeyDenied,
fixAction: GitErrorFixAction.openAccountManagement,
);
}
if (text.contains('bad permissions') ||
text.contains('unprotected private key file') ||
text.contains('load key') ||
text.contains('error in libcrypto')) {
return const GitErrorInfo(
kind: GitOperationErrorKind.sshKeyUnusable,
fixAction: GitErrorFixAction.openAccountManagement,
);
}
// ---- 5. 网络类 ----
if (text.contains('could not resolve host') ||
text.contains('name or service not known') ||
text.contains('network is unreachable') ||
text.contains('connection timed out') ||
text.contains('connection refused') ||
text.contains('failed to connect') ||
text.contains('could not resolve proxy') ||
text.contains('operation timed out') ||
text.contains('ssl certificate problem') ||
text.contains('gnutls_handshake')) {
return const GitErrorInfo(kind: GitOperationErrorKind.networkUnreachable);
}
// ---- 6. 冲突(rebase/merge 中途)----
// `could not apply` 是 rebase 冲突的标志性输出。
if (conflictMarkers.any(text.contains) ||
text.contains('merge conflict') ||
text.contains('needs merge')) {
return const GitErrorInfo(
kind: GitOperationErrorKind.conflictDetected,
fixAction: GitErrorFixAction.abortRebase,
);
}
// ---- 7. 推送被拒(non-fast-forward)----
if (text.contains('non-fast-forward') ||
text.contains('failed to push some refs') ||
text.contains('updates were rejected') ||
text.contains('fetch first') ||
text.contains('tip of your current branch is behind')) {
return const GitErrorInfo(
kind: GitOperationErrorKind.nonFastForward,
fixAction: GitErrorFixAction.pullThenPush,
);
}
// ---- 8. 未设置上游 ----
if (text.contains('has no upstream branch') ||
text.contains('no upstream configured') ||
text.contains('set-upstream')) {
return const GitErrorInfo(
kind: GitOperationErrorKind.noUpstreamConfigured,
);
}
// ---- 9. 本地改动会被覆盖 ----
if (text.contains('would be overwritten') ||
text.contains('your local changes') ||
text.contains('commit your changes or stash them') ||
text.contains('cannot pull with rebase')) {
return const GitErrorInfo(
kind: GitOperationErrorKind.localChangesWouldBeOverwritten,
);
}
// ---- 10. 引用锁 ----
if ((text.contains('unable to create') && text.contains('.lock')) ||
text.contains('index.lock') ||
text.contains('another git process')) {
return const GitErrorInfo(kind: GitOperationErrorKind.refLockFailed);
}
// ---- 11. 磁盘空间 ----
if (text.contains('no space left on device') || text.contains('disk full')) {
return const GitErrorInfo(kind: GitOperationErrorKind.outOfSpace);
}
// ---- 12. 超时 ----
if (text.contains('超时') ||
text.contains('timed out') ||
text.contains('timeout')) {
return const GitErrorInfo(kind: GitOperationErrorKind.timeout);
}
// ---- 兜底:输出里没有任何可识别的错误 ----
// 典型情况:fetch/push 只留下了 "Enumerating objects: N, done." 这类进度行,
// 说明命令是被超时或连接中断打断的,而不是 git 主动报错。
// 绝不能把进度行当作错误原因展示给用户——那会把排查方向彻底带偏。
final meaningful = firstMeaningfulLine(raw);
if (meaningful == null) {
return const GitErrorInfo(kind: GitOperationErrorKind.operationIncomplete);
}
return GitErrorInfo(
kind: GitOperationErrorKind.unknown,
rawDetail: meaningful,
);
}
/// 便捷判断:命令输出是否代表冲突
static bool isConflict(String stderr, {String stdout = ''}) {
final text = '${stderr.toLowerCase()}\n${stdout.toLowerCase()}';
return conflictMarkers.any(text.contains);
}
/// git 进度输出的阶段名前缀(白名单)
///
/// 必须用白名单:如果把 `^[A-Za-z]+:\s` 当作通用模式,`fatal:` / `error:`
/// 也会被误判成进度行,从而把真正的错误信息丢掉。
static const List<String> _progressPhases = [
'enumerating objects',
'counting objects',
'compressing objects',
'receiving objects',
'resolving deltas',
'writing objects',
'updating files',
];
/// 进度类行(不含真正的错误信息),例如:
/// `remote: Enumerating objects: 2233, done.`
/// `Receiving objects: 45% (450/1000)`
/// `Resolving deltas: 100% (7/7), done.`
static bool _isProgressLine(String line) {
final t = line.trim().toLowerCase();
if (t.isEmpty) return false;
for (final phase in _progressPhases) {
if (t.startsWith(phase)) return true;
}
return false;
}
/// 从多行输出中挑出第一条真正的错误信息;若全是进度噪音则返回 null
static String? firstMeaningfulLine(String raw) {
for (final line in raw.split('\n')) {
final t = line.trim();
if (t.isEmpty) continue;
// 去掉 `remote: ` 前缀后再判断,因为 GitHub 的进度与错误都带这个前缀
final body = t.startsWith('remote:') ? t.substring('remote:'.length).trim() : t;
if (body.isEmpty) continue;
if (_isProgressLine(body)) continue;
return body.length > 300 ? '${body.substring(0, 300)}…' : body;
}
return null;
}
}
/// 错误类型 → 本地化文案的映射
///
/// 放在 UI 可达的扩展里,使 [GitErrorMapper] 本身保持纯逻辑、无 l10n 依赖。
extension GitOperationErrorKindL10n on GitOperationErrorKind {
/// 面向用户的简短说明
String message(AppLocalizations l10n) {
switch (this) {
case GitOperationErrorKind.none:
return l10n.gitErrUnknown;
case GitOperationErrorKind.authFailed:
return l10n.gitErrAuthFailed;
case GitOperationErrorKind.writePermissionDenied:
return l10n.gitErrWritePermissionDenied;
case GitOperationErrorKind.repositoryNotFound:
return l10n.gitErrRepositoryNotFound;
case GitOperationErrorKind.proxyAuthRequired:
return l10n.gitErrProxyAuthRequired;
case GitOperationErrorKind.requestRejected:
return l10n.gitErrRequestRejected;
case GitOperationErrorKind.rateLimited:
return l10n.gitErrRateLimited;
case GitOperationErrorKind.httpError:
return l10n.gitErrHttpError;
case GitOperationErrorKind.passwordAuthDisabled:
return l10n.gitErrPasswordAuthDisabled;
case GitOperationErrorKind.networkUnreachable:
return l10n.gitErrNetworkUnreachable;
case GitOperationErrorKind.sshPublicKeyDenied:
return l10n.gitErrSshPublicKeyDenied;
case GitOperationErrorKind.sshKeyUnusable:
return l10n.gitErrSshKeyUnusable;
case GitOperationErrorKind.hostKeyUnverified:
return l10n.gitErrHostKeyUnverified;
case GitOperationErrorKind.nonFastForward:
return l10n.gitErrNonFastForward;
case GitOperationErrorKind.staleForcePush:
return l10n.gitErrStaleForcePush;
case GitOperationErrorKind.conflictDetected:
return l10n.gitErrConflictDetected;
case GitOperationErrorKind.localChangesWouldBeOverwritten:
return l10n.gitErrLocalChanges;
case GitOperationErrorKind.noUpstreamConfigured:
return l10n.gitErrNoUpstream;
case GitOperationErrorKind.refLockFailed:
return l10n.gitErrRefLockFailed;
case GitOperationErrorKind.outOfSpace:
return l10n.gitErrOutOfSpace;
case GitOperationErrorKind.timeout:
return l10n.gitErrTimeout;
case GitOperationErrorKind.operationIncomplete:
return l10n.gitErrIncomplete;
case GitOperationErrorKind.unknown:
return l10n.gitErrUnknown;
}
}
/// 建议的下一步操作
String suggestion(AppLocalizations l10n) {
switch (this) {
case GitOperationErrorKind.none:
return '';
case GitOperationErrorKind.authFailed:
return l10n.gitErrAuthFailedHint;
case GitOperationErrorKind.writePermissionDenied:
return l10n.gitErrWritePermissionDeniedHint;
case GitOperationErrorKind.repositoryNotFound:
return l10n.gitErrRepositoryNotFoundHint;
case GitOperationErrorKind.proxyAuthRequired:
return l10n.gitErrProxyAuthRequiredHint;
case GitOperationErrorKind.requestRejected:
return l10n.gitErrRequestRejectedHint;
case GitOperationErrorKind.rateLimited:
return l10n.gitErrRateLimitedHint;
case GitOperationErrorKind.httpError:
return l10n.gitErrHttpErrorHint;
case GitOperationErrorKind.passwordAuthDisabled:
return l10n.gitErrPasswordAuthDisabledHint;
case GitOperationErrorKind.networkUnreachable:
return l10n.gitErrNetworkUnreachableHint;
case GitOperationErrorKind.sshPublicKeyDenied:
return l10n.gitErrSshPublicKeyDeniedHint;
case GitOperationErrorKind.sshKeyUnusable:
return l10n.gitErrSshKeyUnusableHint;
case GitOperationErrorKind.hostKeyUnverified:
return l10n.gitErrHostKeyUnverifiedHint;
case GitOperationErrorKind.nonFastForward:
return l10n.gitErrNonFastForwardHint;
case GitOperationErrorKind.staleForcePush:
return l10n.gitErrStaleForcePushHint;
case GitOperationErrorKind.conflictDetected:
return l10n.gitErrConflictDetectedHint;
case GitOperationErrorKind.localChangesWouldBeOverwritten:
return l10n.gitErrLocalChangesHint;
case GitOperationErrorKind.noUpstreamConfigured:
return l10n.gitErrNoUpstreamHint;
case GitOperationErrorKind.refLockFailed:
return l10n.gitErrRefLockFailedHint;
case GitOperationErrorKind.outOfSpace:
return l10n.gitErrOutOfSpaceHint;
case GitOperationErrorKind.timeout:
return l10n.gitErrTimeoutHint;
case GitOperationErrorKind.operationIncomplete:
return l10n.gitErrIncompleteHint;
case GitOperationErrorKind.unknown:
return l10n.gitErrUnknownHint;
}
}
}