@mergelight/cli 0.0.0-stage → 0.1.14

package/dist/publish/closed.js

@@ -0,0 +1,88 @@
+import { trustedComment } from "./handled.js";
+import { FINDING_MARKER_RE } from "./markdown.js";
+/** Older reviews answered a fixed thread with a reply carrying this marker. */
+const GONE_MARKER = "<!-- mergelight:gone -->";
+/** Someone reopened a thread Mergelight closed. It stays open until a person resolves it again. */
+const REOPENED_MARKER = "<!-- mergelight:reopened -->";
+const CLOSED_RE = /<!-- mergelight:closed how=(fixed|resolved) resolved=([01])(?: sha=([a-f0-9]+))? -->/;
+const SUMMARY_END = "</summary>\n\n";
+const DETAILS_END = "\n\n</details>";
+export function readClosed(body) {
+    const m = body.match(CLOSED_RE);
+    return m ? { how: m[1], resolved: m[2] === "1", sha: m[3] ?? null } : null;
+}
+/** The comment with a checkmark on top and the original behind a dropdown, named after the finding. */
+export function closedBody(body, c) {
+    const marker = body.match(FINDING_MARKER_RE)?.[0] ?? "";
+    const original = body.replace(FINDING_MARKER_RE, "").replace(REOPENED_MARKER, "").trim();
+    const label = (original.split("\n")[0] ?? "Original comment").replace(/\*\*/g, "").replace(/</g, "&lt;");
+    const why = c.how === "fixed"
+        ? `The code changed and Mergelight no longer finds this${c.sha ? ` in \`${c.sha}\`` : ""}.`
+        : `Resolved${c.by ? ` by ${c.by}` : ""}.`;
+    return [
+        marker,
+        `<!-- mergelight:closed how=${c.how} resolved=${c.resolved ? 1 : 0}${c.sha ? ` sha=${c.sha}` : ""} -->`,
+        `✅ **Handled.** ${why}`,
+        "",
+        `<details><summary>${label}${SUMMARY_END}${original}${DETAILS_END}`,
+    ].join("\n");
+}
+/** Back to the original comment. */
+export function reopenedBody(body, keepOpen) {
+    const marker = body.match(FINDING_MARKER_RE)?.[0] ?? "";
+    const start = body.indexOf(SUMMARY_END);
+    const end = body.lastIndexOf(DETAILS_END);
+    const original = start >= 0 && end > start ? body.slice(start + SUMMARY_END.length, end) : body;
+    return [marker, ...(keepOpen ? [REOPENED_MARKER] : []), original].join("\n");
+}
+/** The finding a thread is about, if it's one of Mergelight's own. */
+export function threadFinding(t) {
+    const first = t.comments.nodes[0];
+    if (!first)
+        return null;
+    if (!trustedComment({ user: { type: first.author?.__typename }, author_association: first.authorAssociation }))
+        return null;
+    const id = first.body.match(FINDING_MARKER_RE)?.[1];
+    return id ? { id, commentId: first.databaseId, body: first.body } : null;
+}
+/** What this round should do to a thread, given the findings the review still reports. */
+export function threadAction(t, open) {
+    const found = threadFinding(t);
+    if (!found)
+        return null;
+    const closed = readClosed(found.body);
+    const answeredBefore = t.comments.nodes.some((c) => c.body.includes(GONE_MARKER));
+    if (closed) {
+        if (open.has(found.id))
+            return { kind: "regressed", unresolve: closed.how === "fixed" && t.isResolved };
+        // resolved=0 means GitHub wouldn't let the workflow resolve it, so an open thread doesn't mean anyone reopened it.
+        return !t.isResolved && closed.resolved ? { kind: "reopened" } : null;
+    }
+    if (t.isResolved) {
+        if (open.has(found.id))
+            return null;
+        return answeredBefore ? { kind: "fixed", resolve: false } : { kind: "resolved" };
+    }
+    if (answeredBefore || found.body.includes(REOPENED_MARKER))
+        return null;
+    return t.isOutdated && !open.has(found.id) ? { kind: "fixed", resolve: true } : null;
+}
+/**
+ * Findings whose thread someone with write access resolved, with who did it. The
+ * verifier hears about these as a team decision, so a pull request's own author
+ * can't talk it out of a finding: GitHub lets them resolve threads too.
+ */
+export async function resolvedByPeople(threads, canWrite) {
+    const out = new Map();
+    for (const t of threads) {
+        const found = threadFinding(t);
+        const by = t.resolvedBy?.login;
+        if (!found || !t.isResolved || !by)
+            continue;
+        if (readClosed(found.body)?.how === "fixed" || t.comments.nodes.some((c) => c.body.includes(GONE_MARKER)))
+            continue;
+        if (await canWrite(by))
+            out.set(found.id, by);
+    }
+    return out;
+}

package/dist/publish/diff-lines.js

@@ -0,0 +1,50 @@
+export function parsePatch(patch) {
+    const hunks = [];
+    let current = null;
+    let right = 0;
+    for (const line of patch.split("\n")) {
+        const header = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+        if (header) {
+            right = Number(header[1]);
+            current = { start: right, end: right - 1, lines: new Set() };
+            hunks.push(current);
+            continue;
+        }
+        if (!current || line.startsWith("\\"))
+            continue;
+        if (line.startsWith("-"))
+            continue;
+        // Context and added lines both exist on the right side.
+        current.lines.add(right);
+        current.end = right;
+        right++;
+    }
+    return hunks.filter((h) => h.lines.size > 0);
+}
+export async function commentableLines(api, number) {
+    const files = await api.list(`pulls/${number}/files`);
+    const map = new Map();
+    for (const f of files)
+        if (f.patch)
+            map.set(f.filename, parsePatch(f.patch));
+    return map;
+}
+/** Where to put a finding's inline comment, or null if its lines aren't in the diff. */
+export function place(map, file, line, endLine) {
+    const hunks = map.get(file);
+    if (!hunks)
+        return null;
+    const lo = Math.min(line, endLine);
+    const hi = Math.max(line, endLine);
+    for (const h of hunks) {
+        if (h.lines.has(lo) && h.lines.has(hi))
+            return hi > lo ? { start_line: lo, line: hi } : { line: hi };
+    }
+    // Fall back to the nearest commentable line inside the finding's range.
+    for (const h of hunks) {
+        for (let l = hi; l >= lo; l--)
+            if (h.lines.has(l))
+                return { line: l };
+    }
+    return null;
+}

package/dist/publish/handled.js

@@ -0,0 +1,80 @@
+/**
+ * Whether Mergelight's hidden markers in this comment count. Anyone can write a
+ * comment containing them, and they steer what gets posted and what the verifier
+ * reads, so a passer-by's comment must not be taken for ours.
+ */
+export function trustedComment(c) {
+    return c.user?.type === "Bot" || ["OWNER", "MEMBER", "COLLABORATOR"].includes(c.author_association ?? "");
+}
+/**
+ * Who can write to the repository. A workflow token sees a private org member as
+ * CONTRIBUTOR, so the association alone would silently drop their marks.
+ */
+export function writeAccess(api) {
+    const known = new Map();
+    return (login) => {
+        let answer = known.get(login);
+        if (!answer) {
+            answer = api
+                .get(`collaborators/${encodeURIComponent(login)}/permission`)
+                .then((r) => r.permission === "admin" || r.permission === "write")
+                .catch(() => false);
+            known.set(login, answer);
+        }
+        return answer;
+    };
+}
+const MARK_RE = /<!-- mergelight:handled:v1 ([A-Za-z0-9+/=]+) -->/;
+export const MAX_NOTE = 1000;
+export function encodeMark(ids, as, note, sha) {
+    return `<!-- mergelight:handled:v1 ${Buffer.from(JSON.stringify({ ids, as, note, sha })).toString("base64")} -->`;
+}
+export function decodeMark(body) {
+    const m = body?.match(MARK_RE);
+    if (!m)
+        return null;
+    try {
+        const { ids, as, note, sha } = JSON.parse(Buffer.from(m[1], "base64").toString("utf8"));
+        if (!Array.isArray(ids) || (as !== "fixed" && as !== "wont_fix"))
+            return null;
+        return {
+            ids: ids.filter((id) => typeof id === "string" && /^[a-f0-9]+$/.test(id)),
+            as,
+            note: typeof note === "string" ? note.slice(0, MAX_NOTE) : null,
+            sha: typeof sha === "string" ? sha : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** The latest mark per finding, from comments by people who can write to the repository. */
+export async function readMarks(comments, canWrite) {
+    const marked = comments
+        .map((comment) => ({ comment, mark: decodeMark(comment.body) }))
+        .filter((c) => c.mark)
+        .sort((a, b) => Date.parse(a.comment.created_at ?? "") - Date.parse(b.comment.created_at ?? ""));
+    const marks = new Map();
+    for (const { comment, mark } of marked) {
+        const by = comment.user?.login ?? "";
+        if (!trustedComment(comment) && !(by && (await canWrite(by))))
+            continue;
+        for (const id of mark.ids) {
+            marks.set(id, { id, as: mark.as, note: mark.note, sha: mark.sha, by, at: comment.created_at ?? "", url: comment.html_url });
+        }
+    }
+    return marks;
+}
+export function findingState(f, mark, lastReviewAt) {
+    if (mark?.as === "wont_fix")
+        return "wont_fix";
+    if (f.status === "gone")
+        return "gone";
+    if (!mark)
+        return "open";
+    return markedSince(mark, lastReviewAt) ? "fix_pending" : "still_found";
+}
+/** True if the latest review published before this mark, so it can't have taken it into account. */
+export function markedSince(mark, lastReviewAt) {
+    return !lastReviewAt || Date.parse(mark.at) > Date.parse(lastReviewAt);
+}

package/dist/publish/markdown.js

@@ -0,0 +1,231 @@
+import { encodeState } from "./state.js";
+export const SUMMARY_MARKER = "<!-- mergelight:summary -->";
+export const PENDING_MARKER = "<!-- mergelight:pending -->";
+export const findingMarker = (id) => `<!-- mergelight:finding id=${id} -->`;
+export const FINDING_MARKER_RE = /<!-- mergelight:finding id=([a-f0-9]+) -->/;
+/** GitHub's limit for a comment body and a check run summary. */
+const MAX_BODY = 65_000;
+/**
+ * Model text goes into comments, so it must not be able to fake our hidden
+ * markers or ping people.
+ */
+export function clean(text) {
+    return text
+        .replace(/<!--/g, "&lt;!--")
+        .replace(/(^|[^\w`])@(?=[A-Za-z0-9-])/g, "$1@​")
+        .trim();
+}
+export function label(f) {
+    if (f.class === "bug")
+        return f.severity === "minor" ? { dot: "🟠", name: "Minor bug" } : { dot: "🔴", name: "Bug" };
+    if (f.class === "risk")
+        return { dot: "🟡", name: "Risk" };
+    return { dot: "⚪", name: "Small fix" };
+}
+/** Display order: bugs, then risks, then minor bugs, then small fixes. */
+export function rank(f) {
+    if (f.class === "bug")
+        return f.severity === "minor" ? 2 : 0;
+    return f.class === "risk" ? 1 : 3;
+}
+const where = (f) => `\`${f.file}:${f.end_line > f.line ? `${f.line}-${f.end_line}` : f.line}\``;
+export function inlineBody(f) {
+    const { dot, name } = label(f);
+    return [
+        findingMarker(f.id),
+        `${dot} **${name}** · **${clean(f.title)}**`,
+        "",
+        clean(f.how_it_happens),
+        "",
+        `**What breaks:** ${clean(f.what_breaks)}`,
+        "",
+        `**Smallest fix** (${f.fix_cost}): ${clean(f.fix)}`,
+        "",
+        `**→ ${clean(f.verdict)}**`,
+        "",
+        `<sub>${f.likelihood} · ${f.severity} · fix ${f.fix_cost}</sub>`,
+    ].join("\n");
+}
+/** Posted when a review starts, so the summary is the first thing on the pull request. */
+export function pendingSummaryBody() {
+    return [SUMMARY_MARKER, PENDING_MARKER, "### ⏳ Mergelight: Reviewing", "", "This usually takes 2 to 15 minutes. This comment updates when the review is done."].join("\n");
+}
+export const isPendingSummary = (body) => Boolean(body?.includes(PENDING_MARKER));
+export const loginNotice = (plan, reason) => ({ heading: `⚠️ Mergelight: the ${plan} login didn't work`, body: reason });
+export function limitNotice(plan, resets) {
+    const reason = `This pull request wasn't reviewed, because your ${plan} plan has no usage left.`;
+    return {
+        heading: `⏳ Mergelight: your ${plan} plan hit its limit`,
+        body: resets ? `${reason}\n\n**Resets:** ${resets}\n\nPush a new commit after that, and the review runs again.` : `${reason}\n\nPush a new commit once your plan has usage again, and the review runs again.`,
+    };
+}
+/** Marks a summary that only says a run failed, so the next failure can say what's true now. */
+export const FAILED_MARKER = "<!-- mergelight:failed -->";
+const GENERAL_FAILURE = ["### ⚠️ Mergelight couldn't review this pull request", "", "The Mergelight check has the reason. The next push tries again."].join("\n");
+export function failedSummaryBody(notice) {
+    if (notice)
+        return [SUMMARY_MARKER, FAILED_MARKER, `### ${notice.heading}`, "", notice.body].join("\n");
+    return [SUMMARY_MARKER, FAILED_MARKER, GENERAL_FAILURE].join("\n");
+}
+/** Only at the very start, because a summary with results can quote text from the pull request. Earlier releases wrote no marker. */
+export const isFailedSummary = (body) => Boolean(body?.startsWith(`${SUMMARY_MARKER}\n${FAILED_MARKER}\n`) || body?.trim() === `${SUMMARY_MARKER}\n${GENERAL_FAILURE}`);
+export const LIGHT = {
+    red: { dot: "🔴", label: "Blocked" },
+    yellow: { dot: "🟡", label: "Needs a human" },
+    green: { dot: "🟢", label: "Safe to merge" },
+};
+function duration(ms) {
+    const s = Math.round(ms / 1000);
+    return s >= 60 ? `${Math.floor(s / 60)}m ${s % 60}s` : `${s}s`;
+}
+function plural(n, word) {
+    return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+/** One line on what the review found, for the summary and the check title. */
+export function headline(r, handled = 0) {
+    const toFix = r.findings.filter((f) => f.tier === "post" || f.tier === "list");
+    const bugs = toFix.filter((f) => f.class === "bug" && f.severity !== "minor").length;
+    const minor = toFix.filter((f) => f.class === "bug" && f.severity === "minor").length;
+    const risks = toFix.filter((f) => f.class !== "bug").length;
+    const decisions = r.findings.filter((f) => f.tier === "decision").length;
+    const parts = [];
+    if (bugs)
+        parts.push(plural(bugs, "bug"));
+    if (risks)
+        parts.push(plural(risks, "risk"));
+    if (minor)
+        parts.push(plural(minor, "minor bug"));
+    const fix = parts.length ? `${parts.join(", ")} to fix` : "";
+    const call = decisions ? `${decisions} for you to decide` : "";
+    return [fix, call].filter(Boolean).join(", ") || (handled ? "Nothing left to fix" : "Nothing worth fixing");
+}
+/** A finding this review still reports, though someone marked it handled before the review finished. */
+function markTag(mark) {
+    if (!mark)
+        return "";
+    return mark.as === "fixed" ? " _(marked fixed, still found)_" : " _(marked won't fix, still reported)_";
+}
+const escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/** A title as HTML: escaped, with its `code` kept, and no one mentioned by accident. */
+const inlineHtml = (text) => clean(escapeHtml(text)).replace(/`([^`]+)`/g, "<code>$1</code>");
+/** A line for a finding worth fixing. Without an inline comment to link to, the details go here. */
+function fixLine(f, urls, mark) {
+    const { dot, name } = label(f);
+    const url = urls.get(f.id);
+    const tag = markTag(mark);
+    if (url)
+        return [`- ${dot} ${name}: [${clean(f.title)}](${url}) ${where(f)}${tag}`];
+    // Markdown doesn't work inside <summary>, so this line is HTML.
+    const markNote = mark ? ` <i>(${mark.as === "fixed" ? "marked fixed, still found" : "marked won't fix, still reported"})</i>` : "";
+    return [
+        "",
+        `<details><summary>${dot} ${name}: <b>${inlineHtml(f.title)}</b> <code>${escapeHtml(where(f).replaceAll("`", ""))}</code>${markNote}</summary>`,
+        "",
+        clean(f.how_it_happens),
+        "",
+        `**What breaks:** ${clean(f.what_breaks)}`,
+        "",
+        `**Smallest fix** (${f.fix_cost}): ${clean(f.fix)}`,
+        "",
+        `**→ ${clean(f.verdict)}**`,
+        "",
+        "</details>",
+    ];
+}
+const NEWS_SHOWN = 4;
+/** At the top of the comment, because a pinned repo only gets new versions if someone notices and acts. */
+function updateBanner({ tag, current, news }) {
+    const more = news.length - NEWS_SHOWN;
+    return [
+        "> [!IMPORTANT]",
+        `> **You're missing out: Mergelight ${tag} is out, and this repo is on ${current}.**`,
+        ...(news.length ? [">", ...news.slice(0, NEWS_SHOWN).map((n) => `> - ${clean(n)}`), ...(more > 0 ? [`> - and ${more} more`] : [])] : []),
+        ">",
+        "> **[Update now](https://mergelight.dev/setup/)**. It's one click, and only the version lines change.",
+        "",
+    ];
+}
+/** Says what the review couldn't see, so a quiet result isn't taken to cover it. The names are checked against a strict pattern before they get here. */
+export function notReadLine(list) {
+    if (!list?.length)
+        return null;
+    const names = (items) => {
+        const shown = items.slice(0, 4).map((i) => `\`${i.uses.replace(/[^\w./@-]/g, "")}\``);
+        return items.length > 4 ? `${shown.join(", ")} and ${items.length - 4} more` : shown.join(", ");
+    };
+    const programs = list.filter((i) => i.why === "program");
+    const missing = list.filter((i) => i.why === "unreadable");
+    const parts = [
+        programs.length ? `the code that ${names(programs)} ${programs.length === 1 ? "runs" : "run"} (a Node or Docker action, so only ${programs.length === 1 ? "its definition was" : "their definitions were"} read)` : "",
+        missing.length ? `${names(missing)} (couldn't be read)` : "",
+    ].filter(Boolean);
+    return `<sub>Not read: ${parts.join(", and ")}.</sub>`;
+}
+export function summaryBody({ review: r, state, urls, marks = new Map(), handled = new Map(), update }, withState = true) {
+    const light = LIGHT[r.light];
+    const top = r.findings.filter((f) => f.tier === "post").sort((a, b) => (a.rank ?? 9) - (b.rank ?? 9) || rank(a) - rank(b));
+    const listed = r.findings.filter((f) => f.tier === "list").sort((a, b) => rank(a) - rank(b));
+    const decisions = r.findings.filter((f) => f.tier === "decision");
+    const leftAlone = r.findings.filter((f) => f.tier === "hardening");
+    const dropped = state.findings.filter((f) => f.status === "gone" && marks.get(f.id)?.as === "wont_fix");
+    const done = state.findings.filter((f) => dropped.includes(f) || (f.status === "gone" && handled.has(f.id)));
+    const gone = state.round > 1 ? state.findings.filter((f) => f.status === "gone" && f.tier !== "hardening" && !done.includes(f)) : [];
+    const out = [SUMMARY_MARKER, ...(update ? updateBanner(update) : []), `### ${light.dot} Mergelight: ${light.label}`, "", clean(r.summary), "", `**${headline(r, done.length)}**`];
+    if (top.length) {
+        out.push("", "#### To fix");
+        for (const f of top)
+            out.push(...fixLine(f, urls, marks.get(f.id)));
+    }
+    if (listed.length) {
+        // With nothing above it, the count is the heading already, and "also" would point at an empty section.
+        out.push("", ...(top.length ? ["#### Also worth fixing"] : []));
+        for (const f of listed)
+            out.push(...fixLine(f, urls, marks.get(f.id)));
+    }
+    if (decisions.length) {
+        out.push("", "#### Your call", "Real, but whether to fix it is a trade-off for you to make.", "");
+        for (const f of decisions) {
+            out.push(`- **${clean(f.title)}** ${where(f)}: ${clean(f.verdict)}${markTag(marks.get(f.id))}`);
+            out.push(`  <details><summary>How it happens</summary>`, "", `  ${clean(f.how_it_happens)} ${clean(f.what_breaks)}`, "", `  Fix (${f.fix_cost}): ${clean(f.fix)}`, "  </details>");
+        }
+    }
+    if (done.length) {
+        out.push("", `<details><summary>✅ Handled: ${done.length}</summary>`, "");
+        for (const f of done) {
+            const mark = marks.get(f.id);
+            const h = handled.get(f.id);
+            const how = mark?.as === "wont_fix"
+                ? `not fixing. ${clean(mark.note ?? "No reason given.")} (${mark.by})`
+                : h?.how === "fixed"
+                    ? `fixed${h.sha ? ` in \`${h.sha}\`` : ""}`
+                    : `resolved${h?.by ? ` by ${h.by}` : ""}`;
+            const url = urls.get(f.id) ?? f.url;
+            out.push(`- ✅ ${url ? `[${clean(f.title)}](${url})` : clean(f.title)} \`${f.file}:${f.line}\`: ${how}`);
+        }
+        out.push("", "</details>");
+    }
+    if (leftAlone.length) {
+        out.push("", `<details><summary>Left alone: ${plural(leftAlone.length, "smaller finding")}</summary>`, "");
+        for (const f of leftAlone)
+            out.push(`- ${clean(f.title)} ${where(f)}: ${clean(f.verdict)}`);
+        out.push("", "</details>");
+    }
+    if (gone.length) {
+        out.push("", `<details><summary>No longer found since the last review: ${gone.length}</summary>`, "");
+        for (const f of gone)
+            out.push(`- ${clean(f.title)} \`${f.file}:${f.line}\``);
+        out.push("", "</details>");
+    }
+    const unread = notReadLine(r.not_read);
+    if (unread)
+        out.push("", unread);
+    const who = (p) => `${p.name === "codex" ? "Codex" : "Claude"}${p.model ? ` ${p.model.replace(/^claude-/, "")}` : ""}`;
+    const checkedBy = r.verifier && r.verifier.name !== r.provider.name ? `, checked by ${who(r.verifier)},` : "";
+    out.push("", `<sub>Round ${state.round} · reviewed \`${r.pr.head_sha.slice(0, 7)}\` with ${who(r.provider)}${checkedBy} on your own plan · ${duration(r.stats.duration_ms)}</sub>`);
+    const tail = withState ? `\n${encodeState(state)}` : "";
+    const room = MAX_BODY - tail.length;
+    let body = out.join("\n");
+    if (body.length > room)
+        body = `${body.slice(0, room - 200)}\n\n_Summary cut short: too many findings to list._`;
+    return `${body}${tail}`;
+}