dsh-github-flow 0.5.0 → 0.7.0

package/lib/executor/git-parser.js

@@ -253,3 +253,400 @@ export function parseGitStatText(statText) {
         return null;
     return { files, summary };
 }
+/**
+ * 提取 `.git/config` 中所有 `[remote "..."]` 段内的 url。
+ *
+ * 为什么必须按段扫描而不是全文抓 `url = `：`[submodule "..."]` 段同样带 url
+ * （实测 `[submodule "lib"] url = https://github.com/x/y.git`）。全文正则会把
+ * 子模块的远程算进指纹，导致一次 `git submodule add` 就触发整个面板缓存的
+ * 无谓作废。子模块的 url 与本工作区关联哪个 GitHub 仓库毫无关系。
+ *
+ * 输出语义：保持文件中的出现顺序、已去重、不含空值。
+ * 排序交给调用方（指纹需要稳定顺序，但那是调用方的语义，纯函数不该替它决定）。
+ */
+export function parseRemoteUrls(configText) {
+    return parseGitConfig(configText).allUrls;
+}
+/**
+ * 规范化 git 配置值：处理引号包裹与行尾注释。
+ *
+ * git 的实际规则（全部实测）：
+ *   - 未加引号：`;` 或 `#` 之后一律视为注释，**即使前面没有空格**
+ *       `url = https://github.com/a/b.git ; note`  → https://github.com/a/b.git
+ *       `url = https://github.com/a/b.git;note`    → https://github.com/a/b.git
+ *   - 加引号：引号内的 `;` / `#` 是字面值，注释只能出现在闭合引号之后
+ *       `url = "https://user:p#ss@github.com/a/b.git"` → 保留 #
+ *       `url = "https://github.com/a/b.git" ; note`    → 剥掉引号与注释
+ *   - 引号内支持反斜杠转义
+ *
+ * 为什么必须处理：不剥注释会让 `url = https://github.com/a/b.git ; note`
+ * 解析失败（URL 尾部带注释文本），用户手写的 config 里这很常见。
+ */
+function unquoteValue(raw) {
+    const v = raw.trim();
+    if (!v)
+        return '';
+    // 引号形态：取引号内内容（支持 \" 转义），忽略闭合引号之后的一切
+    const q = v[0];
+    if (q === '"' || q === "'") {
+        let out = '';
+        for (let i = 1; i < v.length; i++) {
+            const ch = v[i];
+            if (ch === '\\' && i + 1 < v.length) {
+                out += v[i + 1];
+                i++;
+                continue;
+            }
+            if (ch === q)
+                return out.trim();
+            out += ch;
+        }
+        // 引号未闭合：按未加引号处理（畸形配置，尽力而非报错）
+        return out.trim();
+    }
+    // 未加引号：首个 ; 或 # 起为注释
+    const cut = v.search(/[;#]/);
+    return (cut >= 0 ? v.slice(0, cut) : v).trim();
+}
+/**
+ * 解析 `.git/config` 与 `HEAD`，产出与 git 语义一致的远程视图。
+ *
+ * 为什么把 HEAD 一起解析：`branch.<name>.remote` 的 `<name>` 是**当前分支**，
+ * 不知道当前分支就无法按 git 的规则选出 remote，只能退化成「取第一个」——
+ * 那正是本次要修的错误。
+ *
+ * @param configText `.git/config` 全文
+ * @param headText   HEAD 文件全文。worktree 场景必须传**局部 gitdir** 下的那个，
+ *                   传共享目录的会拿到主工作树分支名（实测两者不同）。
+ */
+export function parseGitConfig(configText, headText) {
+    const remotes = [];
+    const allUrls = [];
+    const branchRemoteByName = new Map();
+    if (typeof configText === 'string' && configText) {
+        // 当前所处 section：'remote' / 'branch' / null（其他段）
+        let section = null;
+        let sectionName = '';
+        for (const rawLine of configText.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            if (!line || line.startsWith('#') || line.startsWith(';'))
+                continue;
+            if (line.startsWith('[')) {
+                // `[remote "origin"]` / `[remote.origin]` 两种段头都认。
+                // 前瞻断言排除 `[remote-tracking]` 这类同前缀但语义无关的段
+                // （`\b` 做不到——`-` 是非单词字符，会被判为词边界）。
+                const quoted = /^\[\s*(remote|branch)\s+"([^"]*)"\s*\]/i.exec(line);
+                const dotted = /^\[\s*(remote|branch)\.([^\s\]]+)\s*\]/i.exec(line);
+                const m = quoted || dotted;
+                if (m) {
+                    section = m[1].toLowerCase();
+                    sectionName = m[2];
+                }
+                else {
+                    section = null;
+                    sectionName = '';
+                }
+                continue;
+            }
+            if (!section)
+                continue;
+            if (section === 'remote') {
+                const mu = /^url\s*=\s*(.+)$/i.exec(line);
+                if (mu) {
+                    const url = unquoteValue(mu[1]);
+                    if (url) {
+                        // 指纹收集全部 url 行（含同 remote 的第二行）
+                        if (!allUrls.includes(url))
+                            allUrls.push(url);
+                        // 身份映射只保留首个：git 对同名 remote 的多 url 也只认第一个
+                        if (!remotes.some((r) => r.name === sectionName)) {
+                            remotes.push({ name: sectionName, url });
+                        }
+                    }
+                    continue;
+                }
+                // upstream 段写在前面时也要能读到——这里不做任何顺序假设
+            }
+            else if (section === 'branch') {
+                const mr = /^remote\s*=\s*(.+)$/i.exec(line);
+                if (mr) {
+                    const value = unquoteValue(mr[1]);
+                    if (value)
+                        branchRemoteByName.set(sectionName, value);
+                }
+            }
+        }
+    }
+    // HEAD 形态：`ref: refs/heads/main` → main；40 位 sha（detached）→ null
+    let currentBranch = null;
+    if (typeof headText === 'string' && headText) {
+        const mh = /^\s*ref:\s*refs\/heads\/(.+?)\s*$/m.exec(headText);
+        if (mh)
+            currentBranch = mh[1];
+    }
+    const branchRemote = currentBranch ? branchRemoteByName.get(currentBranch) ?? null : null;
+    return { remotes, allUrls, currentBranch, branchRemote };
+}
+/**
+ * 按 git 的规则选出「这个工作区关联的 remote」。
+ *
+ * 优先级与 git 一致：
+ *   1. `branch.<当前分支>.remote` —— 当前分支显式跟踪的 remote
+ *   2. `origin`                  —— git 的默认远程
+ *   3. 第一个 remote              —— 兜底（保持既有行为）
+ *
+ * 特殊值 `.` 表示跟踪**本地分支**而非远程（实测可设置），跳过第 1 级——
+ * 拿 "." 去查 `[remote "."]` 必然查不到，且语义上它根本不是远程。
+ */
+export function resolveRemoteTarget(cfg) {
+    const remotes = Array.isArray(cfg?.remotes) ? cfg.remotes : [];
+    if (remotes.length === 0)
+        return null;
+    const branchRemote = cfg?.branchRemote;
+    if (branchRemote && branchRemote !== '.') {
+        const hit = remotes.find((r) => r.name === branchRemote);
+        if (hit)
+            return hit;
+    }
+    const origin = remotes.find((r) => r.name === 'origin');
+    if (origin)
+        return origin;
+    return remotes[0];
+}
+/**
+ * 从 remote url 中提取 GitHub 的 owner/repo。
+ *
+ * 覆盖形态（均实测于真实 clone / hand-written config）：
+ *   https://github.com/o/r.git
+ *   git@github.com:o/r.git
+ *   ssh://git@github.com/o/r.git
+ *   https://user:token@github.com/o/r.git
+ *   带尾斜杠 / 不带 .git
+ *
+ * 非 github.com 的 host 一律返回 null（GHE 不在支持范围）。
+ * 为什么绝不"猜一个"：错误身份比没有身份更有害——面板会显示一个
+ * 用户根本不认识的仓库，且所有后续判断都建立在错误前提上。
+ * 正则两端锚定，杜绝 `github.com.evil.com` 这类子串误匹配。
+ */
+export function parseGithubUrl(url) {
+    if (typeof url !== 'string' || !url)
+        return null;
+    const m = /^(?:[a-z][a-z0-9+.-]*:\/\/)?(?:[^@/\s]+@)?github\.com[:/]+([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/i.exec(url.trim());
+    if (!m)
+        return null;
+    const owner = m[1];
+    const repo = m[2];
+    // 排除 `.` / `..` 这类目录穿越形态被当成仓库名
+    if (!owner || !repo || repo === '.' || repo === '..')
+        return null;
+    return { owner, repo };
+}
+/**
+ * 从 remote url 中提取 host（小写）。
+ *
+ * 覆盖：https://host/o/r、git@host:o/r、ssh://git@host:2222/o/r、带 token 的 https。
+ * 无法解析返回 null。
+ *
+ * 为什么不直接复用 parseGithubUrl：本函数要处理**任意 host**（GHE / GitLab），
+ * 用于判断「这个 remote 是不是 GitHub」，而不是「这个 remote 属于哪个 GitHub 仓库」。
+ */
+export function parseRemoteHost(url) {
+    if (typeof url !== 'string' || !url)
+        return null;
+    const raw = url.trim();
+    // 本地路径形态不是"远程 host"，必须显式排除：
+    //   file:///c/Users/me/repo   → 否则会解析出 host "file"
+    //   C:\local\repo             → 否则会解析出 host "c"（盘符）
+    // 这两类的误判虽不影响 classifyRepoLayout（它只比对 'github.com'），
+    // 但违反本函数「无法解析返回 null」的契约，会误导后续调用方。
+    if (/^file:/i.test(raw))
+        return null;
+    if (/^[a-zA-Z]:[\\/]/.test(raw))
+        return null;
+    const m = /^(?:[a-z][a-z0-9+.-]*:\/\/)?(?:[^@/\s]+@)?([^/:\s]+)[:/]/i.exec(raw);
+    if (!m)
+        return null;
+    const host = m[1].toLowerCase();
+    // 单字母多半是盘符残留；含空格不可能出现在 host 位置
+    if (host.length < 2 || host === '.' || host.includes(' '))
+        return null;
+    return host;
+}
+/**
+ * 判断工作区处于哪种远程布局。
+ *
+ * 为什么需要分类而不是顺序盲扫：S2 的兜底逻辑按 `.git/config` 的书写顺序
+ * 挑第一个能解析出 GitHub 身份的 remote，而用户执行 `git remote rename` /
+ * `git remote add` 的先后会改变这个顺序——同一个工作区在两次配置操作后
+ * 可能解析出不同仓库。分类后每种布局的处置规则固定，与顺序无关。
+ *
+ * 分类只看 host 与 git 选中的 remote，不看 URL 的仓库名——后者是身份层的事。
+ */
+export function classifyRepoLayout(cfg) {
+    const remotes = Array.isArray(cfg?.remotes) ? cfg.remotes : [];
+    if (remotes.length === 0)
+        return 'no-remote';
+    const isGithub = (u) => parseRemoteHost(u) === 'github.com';
+    const githubRemotes = remotes.filter((r) => isGithub(r.url));
+    if (githubRemotes.length === 0)
+        return 'no-github';
+    if (githubRemotes.length === remotes.length)
+        return 'github-only';
+    return 'github-mixed';
+}
+/**
+ * 在混合布局中确定性地选出一个 GitHub remote。
+ *
+ * 规则（与书写顺序无关）：
+ *   1. 名字为 `origin` 的优先
+ *   2. 否则按 remote 名字字典序最小的
+ *
+ * 为什么用字典序而不是「第一个出现的」：后者让同一个工作区的解析结果
+ * 依赖用户执行 git remote 命令的先后，属于不可复现的行为。
+ * 字典序是可复现、可断言的确定性规则。
+ */
+export function pickGithubRemote(cfg) {
+    const remotes = Array.isArray(cfg?.remotes) ? cfg.remotes : [];
+    const github = remotes.filter((r) => parseRemoteHost(r.url) === 'github.com');
+    if (github.length === 0)
+        return null;
+    const origin = github.find((r) => r.name === 'origin');
+    if (origin)
+        return origin;
+    return [...github].sort((a, b) => a.name.localeCompare(b.name))[0];
+}
+/**
+ * 解码 git 的 C 风格路径转义（`core.quotePath=true` 时的输出形态）。
+ *
+ * 为什么必须解码：git 的 `core.quotePath` **默认就是 true**，此时非 ASCII 路径
+ * （中文/日文/emoji）会被输出成 `"\344\270\255\346\226\207.txt"` 这种八进制转义。
+ * 而 `gh pr view --json files` 返回的是**真实 UTF-8 路径**——两者不一致会导致
+ * 点击文件时按真实路径查不到 diff，界面显示空白，看起来像"这个文件没改动"。
+ *
+ * 只在后端运行（git-parser 仅被 executor 引用），可安全使用 Buffer 做字节重组。
+ */
+function unquoteGitPath(raw) {
+    const quoted = raw.trim();
+    if (!(quoted.startsWith('"') && quoted.endsWith('"')) || quoted.length < 2)
+        return quoted;
+    const inner = quoted.slice(1, -1);
+    const bytes = [];
+    const simpleEscapes = {
+        n: 10, t: 9, r: 13, '"': 34, '\\': 92, a: 7, b: 8, f: 12, v: 11,
+    };
+    for (let i = 0; i < inner.length; i++) {
+        const ch = inner[i];
+        if (ch === '\\' && i + 1 < inner.length) {
+            const next = inner[i + 1];
+            // 八进制转义：\NNN（git 对非 ASCII 字节统一用 3 位八进制）
+            if (next >= '0' && next <= '7') {
+                const oct = inner.slice(i + 1, i + 4);
+                if (/^[0-7]{3}$/.test(oct)) {
+                    bytes.push(parseInt(oct, 8));
+                    i += 3;
+                    continue;
+                }
+            }
+            if (next in simpleEscapes) {
+                bytes.push(simpleEscapes[next]);
+                i += 1;
+                continue;
+            }
+            bytes.push(ch.charCodeAt(0));
+            continue;
+        }
+        // 普通字符：按其 UTF-8 字节序列入栈（保证与八进制字节混排后可整体还原）
+        for (const b of Buffer.from(ch, 'utf8'))
+            bytes.push(b);
+    }
+    return Buffer.from(bytes).toString('utf8');
+}
+/**
+ * 从 `diff --git <src> <dst>` 行中解析出源路径与目标路径。
+ *
+ * 两种形态都要支持：
+ *   1. 未加引号：`diff --git a/src/app.ts b/src/app.ts`
+ *   2. 加引号：`diff --git "a/\344\270\255.txt" "b/\344\270\255.txt"`
+ *      —— core.quotePath=true（git 默认值）下的非 ASCII 路径形态，需转义还原。
+ *
+ * 未加引号形态的分割点判定为什么不能用「第一个」或「最后一个 ` b/`」：
+ * 路径本身就可能含 ` b/` 子串（如 `diff --git a/x b/y.ts b/x b/y.ts`）。
+ *   非贪婪 → 在第一个 ` b/` 截断，得到 src=`x` / dst=`y.ts b/x b/y.ts`（错）
+ *   贪婪   → 在最后一个 ` b/` 截断，得到 src=`x b/y.ts b/x` / dst=`y.ts`（也错）
+ * 正确做法：**枚举所有 ` b/` 分割点，优先选让两侧路径相等的那个**——
+ * 因为除重命名外 git 的 src 与 dst 本就同路径。重命名场景退化为取首个分割点。
+ */
+function parseDiffGitHeader(line) {
+    const body = line.replace(/^diff --git\s+/, '').trim();
+    if (!body)
+        return null;
+    // 形态 2：两侧均为带引号字符串
+    if (body.startsWith('"')) {
+        const m = /^("(?:[^"\\]|\\.)*")\s+("(?:[^"\\]|\\.)*")$/.exec(body);
+        if (!m)
+            return null;
+        return { src: unquoteGitPath(m[1]), dst: unquoteGitPath(m[2]) };
+    }
+    // 形态 1：逐分割点尝试，优先两侧等值
+    if (!body.startsWith('a/'))
+        return null;
+    const rest = body.slice(2);
+    const positions = [];
+    let idx = rest.indexOf(' b/');
+    while (idx >= 0) {
+        positions.push(idx);
+        idx = rest.indexOf(' b/', idx + 1);
+    }
+    if (positions.length === 0)
+        return null;
+    for (const p of positions) {
+        const srcPart = rest.slice(0, p);
+        const dstPart = rest.slice(p + 1); // 跳过空格，保留 "b/..." 前缀
+        if (dstPart.startsWith('b/') && dstPart.slice(2) === srcPart) {
+            return { src: `a/${srcPart}`, dst: dstPart };
+        }
+    }
+    // 重命名等两侧路径确实不同的场景：取首个分割点
+    const p = positions[0];
+    return { src: `a/${rest.slice(0, p)}`, dst: rest.slice(p + 1) };
+}
+/**
+ * 将整段 Git Unified Diff 纯文本按变动文件切分为字典映射。
+ *
+ * 为什么需要按文件切片：PR 可能会修改数十个文件，前端需要支持「点击某个文件即刻查看该文件改动」。
+ * 在内存做切片索引后，切换文件无需发起网络请求（0ms 响应），体验极致流畅。
+ *
+ * 键必须与 `gh pr view --json files` 返回的 `files[].path` **逐字一致**，
+ * 否则点击文件查不到 diff。因此需要处理 core.quotePath 的八进制转义。
+ *
+ * @param rawDiff gh pr diff 或 git diff 输出的原始文本
+ * @returns 映射字典：{ [filePath: string]: string (该文件的完整 diff 文本段) }
+ */
+export function splitUnifiedDiff(rawDiff) {
+    const fileDiffs = {};
+    if (typeof rawDiff !== 'string' || !rawDiff)
+        return fileDiffs;
+    // 使用正向前瞻匹配每一个 `diff --git ` 开头的分界线
+    const chunks = rawDiff.split(/(?=^diff --git )/m);
+    for (const chunk of chunks) {
+        const trimmed = chunk.trim();
+        if (!trimmed.startsWith('diff --git'))
+            continue;
+        const firstLine = trimmed.split(/\r?\n/, 1)[0] || '';
+        const parsed = parseDiffGitHeader(firstLine);
+        if (!parsed)
+            continue;
+        const { src, dst } = parsed;
+        // 统一剥掉 a/ 与 b/ 前缀，得到仓库内的相对路径
+        const srcPath = src.replace(/^[ab]\//, '');
+        const dstPath = dst.replace(/^[ab]\//, '');
+        // 删除文件时目标侧是 /dev/null，必须回退用源路径作为键，
+        // 否则该文件的 diff 会被挂到一个不存在的 "/dev/null" 键上，永远查不到。
+        const isDeletion = dstPath === 'dev/null' || dstPath === '/dev/null';
+        const targetPath = isDeletion ? srcPath : dstPath;
+        if (targetPath) {
+            fileDiffs[targetPath] = trimmed;
+        }
+    }
+    return fileDiffs;
+}

package/lib/executor/pr-review.d.ts

@@ -0,0 +1,95 @@
+/**
+ * PR 行级评注写入：payload 构造、校验与 422 降级（纯函数）。
+ *
+ * 为什么单独一个模块：
+ * 1. `gh pr review` 没有行级参数（`gh pr review --help` 里 line/side/path 零命中），
+ *    只能走 `POST /repos/{owner}/{repo}/pulls/{n}/reviews` 的 `comments[]`；
+ * 2. 「哪些错误可以在发请求前拦住」「422 怎么降级」是纯逻辑，必须能脱离网络单测；
+ * 3. executor 只负责发请求，校验与降级策略放在这里，避免 executor 继续膨胀。
+ *
+ * 严格按 REST 文档字段构造请求体，未自造任何键。
+ */
+/** 单次 review 的行级评注上限。超过就拆多次，一次一个请求 = 通知只发一轮 */
+export declare const MAX_REVIEW_COMMENTS = 50;
+export type PrReviewEvent = 'COMMENT' | 'APPROVE' | 'REQUEST_CHANGES';
+/** 调用方传入的单条行级评注（宽松类型，校验后才是 REST 形状） */
+export interface PrReviewCommentInput {
+    path?: unknown;
+    line?: unknown;
+    side?: unknown;
+    start_line?: unknown;
+    start_side?: unknown;
+    body?: unknown;
+}
+/** REST 形状的单条评注（全部字段已归一化） */
+export interface PrReviewCommentPayload {
+    path: string;
+    line?: number;
+    side?: 'LEFT' | 'RIGHT';
+    start_line?: number;
+    start_side?: 'LEFT' | 'RIGHT';
+    /**
+     * `file` = 文件级评论（不挂行），`line` = 行级评论。
+     *
+     * 为什么需要它：REST 的 `comments[]` 里 `line` 是**实际必填**的（缺了就 422），
+     * 想只评论某个文件必须显式声明 `subject_type: 'file'`。不写这个字段时，
+     * 「只给 path 不给 line」会被 GitHub 判为非法行级评论——那正是「明明参数合法却 422」的成因。
+     */
+    subject_type?: 'file' | 'line';
+    body: string;
+}
+/** REST 形状的 review 请求体 */
+export interface PrReviewPayload {
+    commit_id?: string;
+    event: PrReviewEvent;
+    body?: string;
+    comments?: PrReviewCommentPayload[];
+}
+export interface BuildResult {
+    ok: boolean;
+    payload?: PrReviewPayload;
+    /** 校验失败时的**全部**问题（一次说完，不要让调用方改一条试一次） */
+    errors?: string[];
+}
+/** `createPrReview` 的返回形状 */
+export interface PrReviewResult {
+    ok: boolean;
+    error?: string;
+    /** 是否走了 422 降级（行级评注被折叠进正文） */
+    degraded?: boolean;
+    /** 降级原因，供渲染层用 appendDegradedNote 显式呈现 */
+    degradedReason?: string;
+    data?: any;
+}
+/**
+ * 构造 REST review 请求体。
+ *
+ * @param input.event    review 判定，缺省 COMMENT
+ * @param input.body     整体说明
+ * @param input.comments 行级评注（空数组等价于不传 → 调用方应走原 gh pr review 路径）
+ * @param input.commit_id 可选锚点 SHA
+ */
+export declare function buildPrReviewPayload(input: {
+    event?: unknown;
+    body?: unknown;
+    comments?: unknown;
+    commit_id?: unknown;
+}): BuildResult;
+/**
+ * 422 降级：把行级评注折叠进 review 正文。
+ *
+ * 为什么必须降级而不是直接失败：422 的典型原因是「该行不在 diff 的 RIGHT 侧」
+ * （纯删除行、未变更的上下文行）。内容本身是对的，只是挂不到那一行上——
+ * 丢掉它等于让 Agent 白干一轮，而把内容塞进正文至少保证意见送达。
+ *
+ * 每条降级项都带 `path:line` 前缀，人能在正文里定位；调用方另需回传
+ * `degraded: true` + `degradedReason`，让「这是降级结果」显式可见。
+ */
+export declare function foldCommentsIntoBody(comments: PrReviewCommentPayload[], baseBody?: string): string;
+/**
+ * 判定失败是否属于「行级评注被拒绝」这一类（值得降级重试）。
+ *
+ * 判据来自 gh 实测 stderr：REST 422 会以 `HTTP 422` 或 `Validation Failed` 出现；
+ * 403/404/网络错误**不在**此列——那些降级也没用，必须原样抛给调用方。
+ */
+export declare function isLineCommentRejected(errorText: string): boolean;

package/lib/executor/pr-review.js

@@ -0,0 +1,175 @@
+/**
+ * PR 行级评注写入：payload 构造、校验与 422 降级（纯函数）。
+ *
+ * 为什么单独一个模块：
+ * 1. `gh pr review` 没有行级参数（`gh pr review --help` 里 line/side/path 零命中），
+ *    只能走 `POST /repos/{owner}/{repo}/pulls/{n}/reviews` 的 `comments[]`；
+ * 2. 「哪些错误可以在发请求前拦住」「422 怎么降级」是纯逻辑，必须能脱离网络单测；
+ * 3. executor 只负责发请求，校验与降级策略放在这里，避免 executor 继续膨胀。
+ *
+ * 严格按 REST 文档字段构造请求体，未自造任何键。
+ */
+import { normalizeSeverity } from '../review-rules.js';
+/** 单次 review 的行级评注上限。超过就拆多次，一次一个请求 = 通知只发一轮 */
+export const MAX_REVIEW_COMMENTS = 50;
+function toPositiveInt(v) {
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) && Number.isInteger(n) && n > 0 ? n : null;
+}
+/**
+ * 归一化单条评注。
+ *
+ * 归一化而非报错的项：`side` 非法 → 回落到 `RIGHT`（新代码侧是最常见意图，
+ * 且报错会让一次批量 review 因为一个拼写错误整体失败）。
+ * 必须报错的项：缺 `path` / 缺 `body` / `line` 给了但不是正整数——
+ * 这三类在 REST 侧必然 422，提前拦住比事后降级更诚实。
+ */
+function normalizeComment(raw, index) {
+    const errors = [];
+    const at = `comments[${index}]`;
+    const p = typeof raw?.path === 'string' ? raw.path.trim() : '';
+    if (!p)
+        errors.push(`${at}.path 必填（文件相对路径）`);
+    const body = typeof raw?.body === 'string' ? raw.body.trim() : '';
+    if (!body)
+        errors.push(`${at}.body 必填（评注正文不能为空）`);
+    let line;
+    if (raw?.line !== undefined && raw?.line !== null) {
+        const n = toPositiveInt(raw.line);
+        if (n === null)
+            errors.push(`${at}.line 必须是正整数（当前 ${JSON.stringify(raw.line)}）`);
+        else
+            line = n;
+    }
+    let startLine;
+    if (raw?.start_line !== undefined && raw?.start_line !== null) {
+        const n = toPositiveInt(raw.start_line);
+        if (n === null)
+            errors.push(`${at}.start_line 必须是正整数（当前 ${JSON.stringify(raw.start_line)}）`);
+        else
+            startLine = n;
+    }
+    if (line !== undefined && startLine !== undefined && startLine > line) {
+        errors.push(`${at}.start_line(${startLine}) 不能大于 line(${line})`);
+    }
+    const sideRaw = typeof raw?.side === 'string' ? raw.side.toUpperCase() : '';
+    const side = sideRaw === 'LEFT' ? 'LEFT' : 'RIGHT';
+    const startSideRaw = typeof raw?.start_side === 'string' ? raw.start_side.toUpperCase() : '';
+    const startSide = startLine === undefined ? undefined : startSideRaw === 'LEFT' ? 'LEFT' : 'RIGHT';
+    if (errors.length > 0)
+        return { ok: false, errors };
+    /*
+     * 没有 line → 文件级评论（`subject_type: 'file'`）。
+     *
+     * 为什么必须显式声明而不是留空：REST 的 `comments[]` 里 `line` 实际是必填的，
+     * 只给 `path` 会被判为「非法行级评论」直接 422。声明成 file 级之后，
+     * 「只想对某个文件留一句」成了合法输入，也不必再走一次注定失败的请求。
+     */
+    if (line === undefined) {
+        return { ok: true, value: { path: p, subject_type: 'file', body: normalizeSeverity(body) } };
+    }
+    return {
+        ok: true,
+        value: {
+            path: p,
+            line,
+            side,
+            ...(startLine !== undefined ? { start_line: startLine, start_side: startSide } : {}),
+            // 严重度前缀在此统一补齐：只补不删，[P0]/[P1] 原样保留
+            body: normalizeSeverity(body),
+        },
+    };
+}
+/**
+ * 构造 REST review 请求体。
+ *
+ * @param input.event    review 判定，缺省 COMMENT
+ * @param input.body     整体说明
+ * @param input.comments 行级评注（空数组等价于不传 → 调用方应走原 gh pr review 路径）
+ * @param input.commit_id 可选锚点 SHA
+ */
+export function buildPrReviewPayload(input) {
+    const errors = [];
+    const rawEvent = typeof input?.event === 'string' ? input.event.toUpperCase() : '';
+    const event = rawEvent === 'APPROVE' || rawEvent === 'REQUEST_CHANGES' || rawEvent === 'COMMENT' ? rawEvent : 'COMMENT';
+    if (rawEvent && rawEvent !== event) {
+        errors.push(`event 只能是 COMMENT / APPROVE / REQUEST_CHANGES（当前 ${JSON.stringify(input.event)}）`);
+    }
+    const list = Array.isArray(input?.comments) ? input.comments : [];
+    if (list.length > MAX_REVIEW_COMMENTS) {
+        errors.push(`单次最多 ${MAX_REVIEW_COMMENTS} 条行级评注（当前 ${list.length} 条），请拆分多次提交`);
+    }
+    const comments = [];
+    for (let i = 0; i < list.length; i++) {
+        const r = normalizeComment(list[i], i);
+        if (r.ok)
+            comments.push(r.value);
+        else
+            errors.push(...r.errors);
+    }
+    const summary = typeof input?.body === 'string' ? input.body.trim() : '';
+    /*
+     * 整体说明只在「提意见」时补严重度前缀，APPROVE 不补。
+     *
+     * 为什么：`[P2] LGTM` 是把优先级标签套在一句同意上，语义上说不通——严重度
+     * 是给**问题**定级的，不是给结论定级的。行级评注则一律补（每条都是一条意见）。
+     */
+    const bodyText = summary
+        ? event === 'APPROVE'
+            ? summary
+            : normalizeSeverity(summary)
+        : comments.length > 0
+            ? `[P2] 共 ${comments.length} 条行级评注`
+            : '';
+    if (!bodyText && event !== 'APPROVE') {
+        errors.push('body 必填：REQUEST_CHANGES / COMMENT 需要一段整体说明');
+    }
+    const commitId = typeof input?.commit_id === 'string' ? input.commit_id.trim() : '';
+    if (commitId && !/^[0-9a-f]{7,40}$/i.test(commitId)) {
+        errors.push(`commit_id 必须是 7–40 位十六进制 SHA（当前 ${JSON.stringify(input.commit_id)}）`);
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    const payload = {
+        event,
+        ...(commitId ? { commit_id: commitId } : {}),
+        ...(bodyText ? { body: bodyText } : {}),
+        ...(comments.length > 0 ? { comments } : {}),
+    };
+    return { ok: true, payload };
+}
+/**
+ * 422 降级：把行级评注折叠进 review 正文。
+ *
+ * 为什么必须降级而不是直接失败：422 的典型原因是「该行不在 diff 的 RIGHT 侧」
+ * （纯删除行、未变更的上下文行）。内容本身是对的，只是挂不到那一行上——
+ * 丢掉它等于让 Agent 白干一轮，而把内容塞进正文至少保证意见送达。
+ *
+ * 每条降级项都带 `path:line` 前缀，人能在正文里定位；调用方另需回传
+ * `degraded: true` + `degradedReason`，让「这是降级结果」显式可见。
+ */
+export function foldCommentsIntoBody(comments, baseBody) {
+    const head = typeof baseBody === 'string' ? baseBody.trim() : '';
+    const parts = [];
+    if (head)
+        parts.push(head);
+    parts.push('---');
+    parts.push('> ⚠️ 以下评注无法挂到具体代码行（该行不在 diff 的可评论侧），已内联到正文。');
+    for (const c of comments) {
+        const where = c.line ? `${c.path}:${c.line}` : c.path;
+        parts.push(`#### \`${where}\`\n\n${c.body}`);
+    }
+    return parts.join('\n\n');
+}
+/**
+ * 判定失败是否属于「行级评注被拒绝」这一类（值得降级重试）。
+ *
+ * 判据来自 gh 实测 stderr：REST 422 会以 `HTTP 422` 或 `Validation Failed` 出现；
+ * 403/404/网络错误**不在**此列——那些降级也没用，必须原样抛给调用方。
+ */
+export function isLineCommentRejected(errorText) {
+    const t = typeof errorText === 'string' ? errorText : '';
+    if (!t)
+        return false;
+    return /HTTP 422|Validation Failed|Unprocessable Entity/i.test(t);
+}