dsh-github-flow 0.5.0 → 0.7.0

package/lib/executor/failure-anchors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * CI 失败日志的「锚点萃取」：把整段日志压成若干段带行号的失败上下文。
+ *
+ * 为什么需要它：
+ * 1. 矩阵构建（matrix）下一个 run 会有 N 个 job 的失败日志，动辄几万行；
+ *    「整段给模型」必然触顶默认输出上限，而截断发生在**萃取之前**——
+ *    结果就是 Agent 只能看到前 24KB，后面的失败根本不存在于上下文里；
+ * 2. 模型真正需要的不是全量日志，而是「每个失败的起点 + 之后几十行」；
+ * 3. 锚点全部取自各框架日志的首列特征（实测输出），不含猜测。
+ *
+ * 纯函数、零 I/O：日志文本进，结构化块出。
+ */
+/** 去掉 gh 的 `job\tstep\ttimestamp ` 前缀（没有前缀时原样返回） */
+export declare function stripLogPrefix(line: string): string;
+export interface FailureBlock {
+    /** 命中的锚点原文（去掉首尾空白，超长截断） */
+    anchor: string;
+    /** 该块起始行号（1-based，方便人去日志里定位） */
+    startLine: number;
+    /** 块正文（含锚点行与其后上下文） */
+    text: string;
+}
+export interface FailureAnchorResult {
+    blocks: FailureBlock[];
+    /** 萃取到的失败块总数（可能大于返回的 blocks.length） */
+    totalBlocks: number;
+    /** 因 maxBlocks 上限被丢弃的块数 */
+    droppedBlocks: number;
+}
+export interface FailureAnchorOptions {
+    /** 每个锚点向后取多少行上下文 */
+    radius?: number;
+    /** 最多返回多少块 */
+    maxBlocks?: number;
+}
+/**
+ * 从日志文本中萃取失败块。
+ *
+ * 合并规则：相邻锚点相距不超过 `radius` 行时并入同一块——同一个异常常常先打
+ * `FAIL` 再打 `AssertionError`，拆成两块等于把一次失败说两遍。
+ * 每块长度上限 `2*radius+1` 行，保证单块不会因为连续堆栈而无限膨胀。
+ */
+export declare function extractFailureAnchors(text: string, options?: FailureAnchorOptions): FailureAnchorResult;
+/** 把萃取结果渲染成 Markdown（人可读、模型可读，行号显式） */
+export declare function renderFailureAnchors(result: FailureAnchorResult): string;
+/**
+ * 无锚点时的回退：取尾部若干行。
+ *
+ * 为什么取尾部而不是头部：日志的失败结论在末尾（构建工具通常先刷编译输出、
+ * 最后才打印错误汇总），取头部基本只能拿到环境准备信息。
+ */
+export declare function tailLines(text: string, count?: number): string;

package/lib/executor/failure-anchors.js

@@ -0,0 +1,116 @@
+/**
+ * CI 失败日志的「锚点萃取」：把整段日志压成若干段带行号的失败上下文。
+ *
+ * 为什么需要它：
+ * 1. 矩阵构建（matrix）下一个 run 会有 N 个 job 的失败日志，动辄几万行；
+ *    「整段给模型」必然触顶默认输出上限，而截断发生在**萃取之前**——
+ *    结果就是 Agent 只能看到前 24KB，后面的失败根本不存在于上下文里；
+ * 2. 模型真正需要的不是全量日志，而是「每个失败的起点 + 之后几十行」；
+ * 3. 锚点全部取自各框架日志的首列特征（实测输出），不含猜测。
+ *
+ * 纯函数、零 I/O：日志文本进，结构化块出。
+ */
+/**
+ * 锚点识别（行首特征）。
+ *
+ * 为什么分两条正则：
+ * 多数框架的失败标记在**行首**（pytest 的 `FAILED path::test`、node 的
+ * `AssertionError`、Go 的 `panic:`），但 TypeScript 编译器的真实输出是
+ * `src/file.ts(3,5): error TS2322: ...` —— 前面带 `文件(行,列):` 前缀，
+ * 行首锚定会一条都命中不了。所以 TS 单独用「行内出现」判定。
+ *
+ * `❌` 单列：本项目自己的 CI 测试输出就是 `❌ FAIL: xxx`，不加这一条
+ * 等于对自己仓库的失败日志完全失明。
+ */
+const ANCHOR_LINE_RE = /^(?:FAIL|FAILED|ERROR|--- FAIL|AssertionError|Error:|panic:|Traceback \(most recent call last\)|npm ERR!|✖|❌)/;
+const ANCHOR_INLINE_RE = /\berror TS\d+:/;
+/**
+ * `gh run view --log-failed` 的每行前缀：`<job>\t<step>\t<ISO8601>Z <正文>`。
+ *
+ * 这是**实测**出来的（不是猜的）：不打掉这个前缀，所有行首都变成 job 名，
+ * 上面两条正则一条也命中不了——锚点萃取会整体退化成「尾部 200 行回退」，
+ * 功能等于不存在。剥离只用于**匹配**，块正文仍保留原始行（job/step 是有用上下文）。
+ */
+const GH_LOG_PREFIX_RE = /^[^\t]*\t[^\t]*\t\d{4}-\d{2}-\d{2}T[0-9:.]+Z\s?/;
+/** 去掉 gh 的 `job\tstep\ttimestamp ` 前缀（没有前缀时原样返回） */
+export function stripLogPrefix(line) {
+    const src = typeof line === 'string' ? line : '';
+    const m = GH_LOG_PREFIX_RE.exec(src);
+    return m ? src.slice(m[0].length) : src;
+}
+/**
+ * 从日志文本中萃取失败块。
+ *
+ * 合并规则：相邻锚点相距不超过 `radius` 行时并入同一块——同一个异常常常先打
+ * `FAIL` 再打 `AssertionError`，拆成两块等于把一次失败说两遍。
+ * 每块长度上限 `2*radius+1` 行，保证单块不会因为连续堆栈而无限膨胀。
+ */
+export function extractFailureAnchors(text, options = {}) {
+    const radius = Number.isFinite(options.radius) && options.radius > 0 ? Math.floor(options.radius) : 15;
+    const maxBlocks = Number.isFinite(options.maxBlocks) && options.maxBlocks > 0 ? Math.floor(options.maxBlocks) : 8;
+    const src = typeof text === 'string' ? text : '';
+    if (!src)
+        return { blocks: [], totalBlocks: 0, droppedBlocks: 0 };
+    const lines = src.split(/\r?\n/);
+    const anchors = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // 先剥 gh 的 job/step/timestamp 前缀，再按行首特征匹配（见 GH_LOG_PREFIX_RE 注释）
+        const body = stripLogPrefix(line).trim();
+        if (ANCHOR_LINE_RE.test(body) || ANCHOR_INLINE_RE.test(body))
+            anchors.push(i);
+    }
+    if (anchors.length === 0)
+        return { blocks: [], totalBlocks: 0, droppedBlocks: 0 };
+    // 分组：相邻锚点间距 > radius 才开新块
+    const groups = [];
+    for (const idx of anchors) {
+        const cur = groups[groups.length - 1];
+        if (!cur || idx - cur.last > radius)
+            groups.push({ start: idx, last: idx });
+        else
+            cur.last = idx;
+    }
+    const maxLines = 2 * radius + 1;
+    const all = groups.map((g) => {
+        const end = Math.min(lines.length, g.last + radius + 1);
+        const slice = lines.slice(g.start, end).slice(0, maxLines);
+        const anchorRaw = lines[g.start].trim();
+        return {
+            anchor: anchorRaw.length > 160 ? anchorRaw.slice(0, 160) + '…' : anchorRaw,
+            startLine: g.start + 1,
+            text: slice.join('\n'),
+        };
+    });
+    const blocks = all.slice(0, maxBlocks);
+    return { blocks, totalBlocks: all.length, droppedBlocks: all.length - blocks.length };
+}
+/** 把萃取结果渲染成 Markdown（人可读、模型可读，行号显式） */
+export function renderFailureAnchors(result) {
+    if (!result || result.blocks.length === 0)
+        return '';
+    const parts = [];
+    parts.push(`**共命中 ${result.totalBlocks} 个失败块**，以下为前 ${result.blocks.length} 个：`);
+    result.blocks.forEach((b, i) => {
+        parts.push(`\n### 失败块 ${i + 1}（日志第 ${b.startLine} 行起）\n\`\`\`\n${b.text}\n\`\`\``);
+    });
+    if (result.droppedBlocks > 0) {
+        parts.push(`\n> ⚠️ 已省略 ${result.droppedBlocks} 个失败块（共 ${result.totalBlocks} 个）。需要时可用更小的范围重跑，或到 Actions 页面查看完整日志。`);
+    }
+    return parts.join('\n');
+}
+/**
+ * 无锚点时的回退：取尾部若干行。
+ *
+ * 为什么取尾部而不是头部：日志的失败结论在末尾（构建工具通常先刷编译输出、
+ * 最后才打印错误汇总），取头部基本只能拿到环境准备信息。
+ */
+export function tailLines(text, count = 200) {
+    const src = typeof text === 'string' ? text : '';
+    if (!src)
+        return '';
+    const lines = src.split(/\r?\n/);
+    if (lines.length <= count)
+        return src;
+    return lines.slice(lines.length - count).join('\n');
+}

package/lib/executor/git-parser.d.ts

@@ -55,3 +55,127 @@ export interface GitStatParsedResult {
  * 提取文件路径与 `X files changed, Y insertions(+), Z deletions(-)` 汇总。
  */
 export declare function parseGitStatText(statText: string): GitStatParsedResult | null;
+/**
+ * 提取 `.git/config` 中所有 `[remote "..."]` 段内的 url。
+ *
+ * 为什么必须按段扫描而不是全文抓 `url = `：`[submodule "..."]` 段同样带 url
+ * （实测 `[submodule "lib"] url = https://github.com/x/y.git`）。全文正则会把
+ * 子模块的远程算进指纹，导致一次 `git submodule add` 就触发整个面板缓存的
+ * 无谓作废。子模块的 url 与本工作区关联哪个 GitHub 仓库毫无关系。
+ *
+ * 输出语义：保持文件中的出现顺序、已去重、不含空值。
+ * 排序交给调用方（指纹需要稳定顺序，但那是调用方的语义，纯函数不该替它决定）。
+ */
+export declare function parseRemoteUrls(configText: string): string[];
+/** 单个 remote 段的解析结果 */
+export interface ParsedRemote {
+    name: string;
+    url: string;
+}
+/** `.git/config` + `HEAD` 的解析结果，是「这个工作区关联哪个仓库」的唯一事实源 */
+export interface ParsedGitConfig {
+    /** 每个 remote 名对应的第一个 url（身份解析用；同名多 url 时取首个） */
+    remotes: ParsedRemote[];
+    /**
+     * 全部 remote url 行（指纹用）。
+     *
+     * 为什么与 remotes 分开：身份解析需要「remote 名 → url」的一对一映射，
+     * 而指纹需要「配置里出现过的所有 url」。同一个 remote 允许写多行 url
+     * （git 认首个，但配置确实是多行），若指纹也按名字去重，第二行 url 的
+     * 变化就检测不到——那会让「用户改了备用 url」这种情况静默漏检。
+     */
+    allUrls: string[];
+    /** 当前分支名（来自 HEAD 的 `ref: refs/heads/<name>`）；detached HEAD 时为 null */
+    currentBranch: string | null;
+    /** `branch.<currentBranch>.remote` 的值；无配置或无当前分支时为 null */
+    branchRemote: string | null;
+}
+/**
+ * 解析 `.git/config` 与 `HEAD`，产出与 git 语义一致的远程视图。
+ *
+ * 为什么把 HEAD 一起解析：`branch.<name>.remote` 的 `<name>` 是**当前分支**，
+ * 不知道当前分支就无法按 git 的规则选出 remote，只能退化成「取第一个」——
+ * 那正是本次要修的错误。
+ *
+ * @param configText `.git/config` 全文
+ * @param headText   HEAD 文件全文。worktree 场景必须传**局部 gitdir** 下的那个，
+ *                   传共享目录的会拿到主工作树分支名（实测两者不同）。
+ */
+export declare function parseGitConfig(configText: string, headText?: string | null): ParsedGitConfig;
+/**
+ * 按 git 的规则选出「这个工作区关联的 remote」。
+ *
+ * 优先级与 git 一致：
+ *   1. `branch.<当前分支>.remote` —— 当前分支显式跟踪的 remote
+ *   2. `origin`                  —— git 的默认远程
+ *   3. 第一个 remote              —— 兜底（保持既有行为）
+ *
+ * 特殊值 `.` 表示跟踪**本地分支**而非远程（实测可设置），跳过第 1 级——
+ * 拿 "." 去查 `[remote "."]` 必然查不到，且语义上它根本不是远程。
+ */
+export declare function resolveRemoteTarget(cfg: ParsedGitConfig): ParsedRemote | null;
+/**
+ * 从 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 declare function parseGithubUrl(url: string): {
+    owner: string;
+    repo: string;
+} | null;
+/**
+ * 从 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 declare function parseRemoteHost(url: string): string | null;
+/**
+ * 判断工作区处于哪种远程布局。
+ *
+ * 为什么需要分类而不是顺序盲扫：S2 的兜底逻辑按 `.git/config` 的书写顺序
+ * 挑第一个能解析出 GitHub 身份的 remote，而用户执行 `git remote rename` /
+ * `git remote add` 的先后会改变这个顺序——同一个工作区在两次配置操作后
+ * 可能解析出不同仓库。分类后每种布局的处置规则固定，与顺序无关。
+ *
+ * 分类只看 host 与 git 选中的 remote，不看 URL 的仓库名——后者是身份层的事。
+ */
+export declare function classifyRepoLayout(cfg: ParsedGitConfig): 'github-only' | 'github-mixed' | 'no-github' | 'no-remote';
+/**
+ * 在混合布局中确定性地选出一个 GitHub remote。
+ *
+ * 规则（与书写顺序无关）：
+ *   1. 名字为 `origin` 的优先
+ *   2. 否则按 remote 名字字典序最小的
+ *
+ * 为什么用字典序而不是「第一个出现的」：后者让同一个工作区的解析结果
+ * 依赖用户执行 git remote 命令的先后，属于不可复现的行为。
+ * 字典序是可复现、可断言的确定性规则。
+ */
+export declare function pickGithubRemote(cfg: ParsedGitConfig): ParsedRemote | null;
+/**
+ * 将整段 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 declare function splitUnifiedDiff(rawDiff: string): Record<string, string>;