@ayushporwal/coja 0.0.1

package/dist/forge/github.js

@@ -0,0 +1,627 @@
+import { HttpError } from '../routes/http.js';
+import { isEmptyFilter } from '../shared/api.js';
+import { ForgeError } from './forge.js';
+import * as q from './queries.js';
+/**
+ * The GitHub implementation of `Forge`, on top of the GraphQL API. GitHub is
+ * the source of truth for all review state (design.md, "Sync model"): nothing
+ * here is cached except the viewer's identity.
+ *
+ * Every mutation in this class is reached only from an HTTP route handler that
+ * a human triggered in the UI. Nothing under server/src/ai may import it.
+ */
+/** Open-PR list pages of 100; a repo with more than this many open PRs is truncated. */
+/** One API page = one GraphQL page; also the contract's `perPage`. */
+export const PR_PAGE_SIZE = 100;
+/** GitHub caps a PR's commit list at 250 regardless of paging (100 + 100 + 50). */
+const MAX_COMMIT_PAGES = 3;
+/** Runaway guard for the other connections (files are capped by GitHub at 3000 = 30 pages). */
+const MAX_PAGES = 50;
+export const COMMENT_LOCATION_REJECTED = 'GitHub rejected the comment location: the line must be part of the pull request diff.';
+export const SUMMARY_REQUIRED = 'Write a summary or add at least one comment first.';
+export class GitHubForge {
+    gql;
+    viewerPromise;
+    /** `owner/repo` + filter → page number → that page's start cursor (page 1 needs none). */
+    prCursors = new Map();
+    /** Per-PR tail of the `addPendingComment` chain, so first comments cannot race (see below). */
+    commentQueues = new Map();
+    constructor(opts) {
+        this.gql = opts.gql;
+    }
+    viewer() {
+        if (!this.viewerPromise) {
+            const p = this.gql(q.VIEWER).then((d) => mapActor(d.viewer));
+            // Do not cache a failure: the next call retries.
+            p.catch(() => {
+                if (this.viewerPromise === p)
+                    this.viewerPromise = undefined;
+            });
+            this.viewerPromise = p;
+        }
+        return this.viewerPromise;
+    }
+    /**
+     * One page of open PRs. A page is exactly one GraphQL page (100 nodes), so
+     * serving page N needs the start cursor of page N: cursors are cached per
+     * repo as they are seen, and a jump past the deepest cached page walks
+     * forward one 100-node query at a time, caching as it goes — later visits
+     * to any known page are a single query again.
+     */
+    async listPullRequestPage(repo, page, filter) {
+        const wanted = Math.max(1, Math.trunc(page));
+        const { login } = await this.viewer();
+        const filtered = filter !== undefined && !isEmptyFilter(filter);
+        // Cursors are cached per repo AND per filter (each filter pages independently).
+        const cursors = this.prPageCursors(repo, filter);
+        // Deepest page at or before the wanted one whose start cursor we know:
+        // walking begins there (a lower cached page needs no walk at all).
+        let start = 1;
+        while (start < wanted && cursors.has(start + 1))
+            start += 1;
+        let items = [];
+        let total = 0;
+        for (let p = start; p <= wanted; p += 1) {
+            const after = cursors.get(p);
+            const connection = filtered
+                ? this.searchConnection(await this.gql(q.PR_SEARCH, {
+                    query: buildSearchQuery(repo, filter),
+                    login,
+                    after,
+                }), repo)
+                : this.listConnection(await this.gql(q.PR_LIST, {
+                    owner: repo.owner,
+                    name: repo.repo,
+                    login,
+                    after,
+                }), repo);
+            total = connection.totalCount ?? 0;
+            const end = connection.pageInfo?.endCursor;
+            const hasNext = connection.pageInfo?.hasNextPage;
+            // Cache the next page's start cursor even when this is the page being
+            // served, so a later visit to page+1 needs no re-walk.
+            if (end && hasNext)
+                cursors.set(p + 1, end);
+            if (p === wanted) {
+                items = (connection.nodes ?? []).filter(nonNull).map(mapSummary);
+                break;
+            }
+            if (!end || !hasNext) {
+                // The list is shorter than the requested page: serve it empty.
+                return this.prPage([], wanted, total);
+            }
+        }
+        return this.prPage(items, wanted, total);
+    }
+    listConnection(d, repo) {
+        const connection = d.repository?.pullRequests;
+        if (!connection)
+            throw repoNotFound(repo);
+        return connection;
+    }
+    searchConnection(d, repo) {
+        if (!d.search)
+            throw new ForgeError(`GitHub search failed for ${repo.owner}/${repo.repo}`);
+        return { ...d.search, totalCount: d.search.issueCount ?? d.search.totalCount };
+    }
+    prPageCursors(repo, filter) {
+        const key = filterKey(repo, filter);
+        let cache = this.prCursors.get(key);
+        if (!cache) {
+            cache = new Map();
+            this.prCursors.set(key, cache);
+        }
+        return cache;
+    }
+    prPage(items, page, total) {
+        return {
+            items,
+            page,
+            perPage: PR_PAGE_SIZE,
+            total,
+            totalPages: Math.max(1, Math.ceil(total / PR_PAGE_SIZE)),
+        };
+    }
+    async getPullRequestRefs(repo, number) {
+        const d = await this.gql(q.PR_REFS, {
+            owner: repo.owner,
+            name: repo.repo,
+            number,
+        });
+        const pr = d.repository?.pullRequest;
+        if (!pr)
+            throw prNotFound(repo, number);
+        return {
+            id: pr.id,
+            number: pr.number,
+            headRefOid: pr.headRefOid,
+            baseRefOid: pr.baseRefOid,
+            baseRefName: pr.baseRefName,
+            headRefName: pr.headRefName,
+        };
+    }
+    async getPullRequest(repo, number) {
+        const viewer = await this.viewer();
+        const vars = { owner: repo.owner, name: repo.repo, number, login: viewer.login };
+        const data = await this.gql(q.PR_DETAIL, vars);
+        const pr = data.repository?.pullRequest;
+        if (!pr)
+            throw prNotFound(repo, number);
+        const page = (doc, pick) => {
+            return async (after) => pick(await this.gql(doc, { ...vars, after })) ?? EMPTY;
+        };
+        const [commits, files, rawThreads, reviews, issueComments] = await Promise.all([
+            drain(pr.commits, page(q.PR_COMMITS_PAGE, (d) => d.repository?.pullRequest?.commits), MAX_COMMIT_PAGES),
+            drain(pr.files, page(q.PR_FILES_PAGE, (d) => d.repository?.pullRequest?.files)),
+            drain(pr.reviewThreads, page(q.PR_THREADS_PAGE, (d) => d.repository?.pullRequest?.reviewThreads)),
+            drain(pr.reviews, page(q.PR_REVIEWS_PAGE, (d) => d.repository?.pullRequest?.reviews)),
+            drain(pr.comments, page(q.PR_ISSUE_COMMENTS_PAGE, (d) => d.repository?.pullRequest?.comments)),
+        ]);
+        const threads = await Promise.all(rawThreads.map(async (t) => {
+            const comments = await drain(t.comments, async (after) => {
+                const d = await this.gql(q.THREAD_COMMENTS_PAGE, {
+                    id: t.id,
+                    after,
+                });
+                return d.node?.comments ?? EMPTY;
+            });
+            return mapThread(t, comments.map((c) => mapComment(c, viewer.login)));
+        }));
+        return {
+            ...mapSummary(pr),
+            body: pr.body,
+            bodyHTML: pr.bodyHTML,
+            commits: commits.map(mapCommit),
+            files: files.map(mapFile),
+            threads,
+            conversation: buildConversation(issueComments, reviews),
+            pendingReview: mapPendingReview(pr.pendingReview?.nodes),
+            viewer,
+        };
+    }
+    /**
+     * Serialized per pull request: two quick first comments would otherwise both
+     * see "no pending review" and each create one, leaving the second invisible
+     * to the UI. A failed comment does not block the ones queued behind it.
+     */
+    addPendingComment(repo, pr, input) {
+        const k = `${repo.owner}/${repo.repo}#${pr.number}`.toLowerCase();
+        const previous = this.commentQueues.get(k) ?? Promise.resolve();
+        const run = previous.then(() => this.addPendingCommentNow(repo, pr, input));
+        const settled = run.then(noop, noop).finally(() => {
+            if (this.commentQueues.get(k) === settled)
+                this.commentQueues.delete(k);
+        });
+        this.commentQueues.set(k, settled);
+        return run;
+    }
+    async addPendingCommentNow(repo, pr, input) {
+        const viewer = await this.viewer();
+        let pending = await this.findPendingReview(repo, pr.number, viewer.login);
+        if (!pending) {
+            const d = await this.gql(q.START_REVIEW, {
+                pullRequestId: pr.id,
+                commitOID: pr.headRefOid,
+            });
+            const review = d.addPullRequestReview?.pullRequestReview;
+            if (!review)
+                throw new ForgeError('GitHub did not create a pending review.', 502);
+            pending = { id: review.id, commentCount: 0 };
+        }
+        const threadInput = {
+            pullRequestReviewId: pending.id,
+            path: input.path,
+            body: input.body,
+            line: input.line,
+            side: input.side,
+        };
+        // A range is anything that does not start exactly where it ends (line and side).
+        const startLine = input.startLine ?? input.line;
+        const startSide = input.startSide ?? input.side;
+        if (startLine !== input.line || startSide !== input.side) {
+            threadInput.startLine = startLine;
+            threadInput.startSide = startSide;
+        }
+        const d = await this.gql(q.ADD_THREAD, { input: threadInput });
+        const thread = d.addPullRequestReviewThread?.thread;
+        if (!thread)
+            throw new ForgeError(COMMENT_LOCATION_REJECTED, 422);
+        const comments = compact(thread.comments.nodes).map((c) => ({
+            ...mapComment(c, viewer.login),
+            reviewId: c.pullRequestReview?.id ?? pending.id,
+            reviewState: 'PENDING',
+            isPending: true,
+            isMine: true,
+        }));
+        const commentCount = compact(thread.firstComment?.nodes)[0]?.pullRequestReview?.comments?.totalCount ??
+            pending.commentCount + 1;
+        return {
+            thread: mapThread(thread, comments),
+            pendingReview: { id: pending.id, commentCount },
+        };
+    }
+    /**
+     * Reply without a pending-review id. Published immediately when the viewer has no pending
+     * review; when one is open GitHub attaches the reply to it instead (observed live), and the
+     * returned comment says so through `isPending` / `reviewId`.
+     */
+    async replyToThread(threadId, body) {
+        const viewer = await this.viewer();
+        const d = await this.gql(q.REPLY, { threadId, body });
+        const comment = d.addPullRequestReviewThreadReply?.comment;
+        if (!comment)
+            throw new ForgeError('GitHub did not return the posted reply.', 502);
+        const mapped = mapComment(comment, viewer.login);
+        const review = comment.pullRequestReview;
+        const pendingReview = mapped.isPending && review
+            ? { id: review.id, commentCount: review.comments?.totalCount ?? 1 }
+            : undefined;
+        return { comment: mapped, threadId, ...(pendingReview ? { pendingReview } : {}) };
+    }
+    async updateComment(commentId, body) {
+        const viewer = await this.viewer();
+        const d = await this.gql(q.UPDATE_COMMENT, { id: commentId, body });
+        const comment = d.updatePullRequestReviewComment?.pullRequestReviewComment;
+        if (!comment)
+            throw new ForgeError('GitHub did not return the updated comment.', 502);
+        return mapComment(comment, viewer.login);
+    }
+    async deleteComment(commentId) {
+        await this.gql(q.DELETE_COMMENT, { id: commentId });
+    }
+    assertCommentInPullRequest(commentId, repo, number) {
+        return this.assertNodeInPullRequest(q.COMMENT_OWNER, commentId, repo, number, 'comment');
+    }
+    assertThreadInPullRequest(threadId, repo, number) {
+        return this.assertNodeInPullRequest(q.THREAD_OWNER, threadId, repo, number, 'thread');
+    }
+    /**
+     * 404 (`not_found`) unless the node resolves, is of the expected type, and
+     * belongs to PR `number` of `repo`. GitHub's own "could not resolve node" is
+     * folded into the same 404 so a bad id is indistinguishable from another PR's.
+     */
+    async assertNodeInPullRequest(doc, id, repo, number, what) {
+        let data;
+        try {
+            data = await this.gql(doc, { id });
+        }
+        catch (err) {
+            if (err instanceof ForgeError && err.status === 404)
+                throw notInPullRequest(what);
+            throw err;
+        }
+        const pr = data.node?.pullRequest;
+        if (!pr ||
+            pr.number !== number ||
+            !sameSlug(pr.repository.owner.login, repo.owner) ||
+            !sameSlug(pr.repository.name, repo.repo)) {
+            throw notInPullRequest(what);
+        }
+    }
+    async setFileViewed(prId, path, viewed) {
+        if (viewed) {
+            await this.gql(q.MARK_VIEWED, { pullRequestId: prId, path });
+            return 'VIEWED';
+        }
+        await this.gql(q.UNMARK_VIEWED, { pullRequestId: prId, path });
+        return 'UNVIEWED';
+    }
+    async submitReview(repo, pr, input) {
+        const viewer = await this.viewer();
+        const pending = await this.findPendingReview(repo, pr.number, viewer.login);
+        const body = input.body.trim() === '' ? undefined : input.body;
+        if (input.event !== 'APPROVE' && body === undefined && !(pending && pending.commentCount > 0)) {
+            throw new HttpError(400, SUMMARY_REQUIRED, 'bad_request');
+        }
+        let review;
+        if (pending) {
+            const d = await this.gql(q.SUBMIT_REVIEW, {
+                reviewId: pending.id,
+                event: input.event,
+                ...(body === undefined ? {} : { body }),
+            });
+            review = d.submitPullRequestReview?.pullRequestReview;
+        }
+        else {
+            const d = await this.gql(q.ADD_AND_SUBMIT_REVIEW, {
+                pullRequestId: pr.id,
+                commitOID: pr.headRefOid,
+                event: input.event,
+                ...(body === undefined ? {} : { body }),
+            });
+            review = d.addPullRequestReview?.pullRequestReview;
+        }
+        if (!review)
+            throw new ForgeError('GitHub did not return the submitted review.', 502);
+        return {
+            reviewId: review.id,
+            state: asReviewState(review.state) ?? 'COMMENTED',
+            ...(review.url ? { url: review.url } : {}),
+        };
+    }
+    async discardPendingReview(repo, number) {
+        const viewer = await this.viewer();
+        const pending = await this.findPendingReview(repo, number, viewer.login);
+        if (!pending)
+            return;
+        await this.gql(q.DISCARD_REVIEW, { reviewId: pending.id });
+    }
+    /** The viewer's pending review on the PR, or null. */
+    async findPendingReview(repo, number, login) {
+        const d = await this.gql(q.PENDING_REVIEW, {
+            owner: repo.owner,
+            name: repo.repo,
+            number,
+            login,
+        });
+        const pr = d.repository?.pullRequest;
+        if (!pr)
+            throw prNotFound(repo, number);
+        return mapPendingReview(pr.reviews?.nodes);
+    }
+}
+// ---------------------------------------------------------------------------
+// Paging
+// ---------------------------------------------------------------------------
+function nonNull(value) {
+    return value !== null;
+}
+const EMPTY = { pageInfo: { hasNextPage: false, endCursor: null }, nodes: [] };
+function compact(nodes) {
+    return (nodes ?? []).filter((n) => n != null);
+}
+/** All nodes of a connection: the page already in hand plus every following page. */
+async function drain(first, more, maxPages = MAX_PAGES) {
+    const out = compact(first.nodes);
+    let page = first;
+    for (let n = 1; n < maxPages && page.pageInfo.hasNextPage && page.pageInfo.endCursor; n++) {
+        page = await more(page.pageInfo.endCursor);
+        out.push(...compact(page.nodes));
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Mapping GitHub's shapes onto the wire types
+// ---------------------------------------------------------------------------
+const REVIEW_STATES = new Set([
+    'PENDING',
+    'COMMENTED',
+    'APPROVED',
+    'CHANGES_REQUESTED',
+    'DISMISSED',
+]);
+const CHANGE_TYPES = new Set([
+    'ADDED',
+    'DELETED',
+    'MODIFIED',
+    'RENAMED',
+    'COPIED',
+    'CHANGED',
+]);
+const VIEWED_STATES = new Set([
+    'VIEWED',
+    'UNVIEWED',
+    'DISMISSED',
+]);
+const asReviewState = (s) => s && REVIEW_STATES.has(s) ? s : undefined;
+const asSide = (s) => (s === 'LEFT' ? 'LEFT' : 'RIGHT');
+const asOptionalSide = (s) => s === 'LEFT' || s === 'RIGHT' ? s : null;
+const asChangeType = (s) => CHANGE_TYPES.has(s) ? s : 'MODIFIED';
+const asViewedState = (s) => VIEWED_STATES.has(s) ? s : 'UNVIEWED';
+/** GitHub renders deleted accounts as "ghost"; a null author maps the same way. */
+export function mapActor(a) {
+    if (!a)
+        return { login: 'ghost' };
+    return a.avatarUrl ? { login: a.login, avatarUrl: a.avatarUrl } : { login: a.login };
+}
+/**
+ * The viewer's own state on a PR: a PENDING review wins; otherwise the most
+ * recently submitted review decides (DISMISSED counts as a plain comment).
+ */
+export function deriveMyReviewState(pending, reviews) {
+    if (compact(pending).length > 0)
+        return 'pending';
+    // GitHub's rule: the newest APPROVED / CHANGES_REQUESTED review is the reviewer's
+    // standing opinion, even when later COMMENTED reviews exist (a published reply
+    // creates one). Only when there is no opinionated review does "commented" apply.
+    let opinion;
+    let commented = false;
+    for (const r of compact(reviews)) {
+        if (r.state === 'PENDING')
+            continue;
+        if (r.state === 'APPROVED' || r.state === 'CHANGES_REQUESTED') {
+            if (!opinion || (r.submittedAt ?? '') > (opinion.submittedAt ?? ''))
+                opinion = r;
+        }
+        else {
+            commented = true;
+        }
+    }
+    if (opinion?.state === 'APPROVED')
+        return 'approved';
+    if (opinion?.state === 'CHANGES_REQUESTED')
+        return 'changes_requested';
+    return commented ? 'commented' : 'none';
+}
+function mapPendingReview(nodes) {
+    const node = compact(nodes)[0];
+    return node ? { id: node.id, commentCount: node.comments?.totalCount ?? 0 } : null;
+}
+export function mapSummary(pr) {
+    return {
+        id: pr.id,
+        number: pr.number,
+        title: pr.title,
+        author: mapActor(pr.author),
+        headRefName: pr.headRefName,
+        baseRefName: pr.baseRefName,
+        headRefOid: pr.headRefOid,
+        baseRefOid: pr.baseRefOid,
+        updatedAt: pr.updatedAt,
+        createdAt: pr.createdAt,
+        isDraft: pr.isDraft,
+        url: pr.url,
+        additions: pr.additions,
+        deletions: pr.deletions,
+        changedFiles: pr.changedFiles,
+        myReviewState: deriveMyReviewState(pr.pendingReview?.nodes, pr.viewerReviews?.nodes),
+    };
+}
+export function mapCommit(c) {
+    const login = c.commit.author?.user?.login;
+    return {
+        oid: c.commit.oid,
+        abbreviatedOid: c.commit.abbreviatedOid,
+        messageHeadline: c.commit.messageHeadline,
+        messageBody: c.commit.messageBody,
+        authorName: c.commit.author?.name ?? login ?? 'unknown',
+        ...(login ? { authorLogin: login } : {}),
+        committedDate: c.commit.committedDate,
+        url: c.url || c.commit.url,
+    };
+}
+export function mapFile(f) {
+    return {
+        path: f.path,
+        additions: f.additions,
+        deletions: f.deletions,
+        changeType: asChangeType(f.changeType),
+        viewedState: asViewedState(f.viewerViewedState),
+    };
+}
+export function mapComment(c, viewerLogin) {
+    const review = c.pullRequestReview;
+    return {
+        id: c.id,
+        ...(typeof c.databaseId === 'number' ? { databaseId: c.databaseId } : {}),
+        body: c.body,
+        bodyHTML: c.bodyHTML,
+        author: mapActor(c.author),
+        createdAt: c.createdAt,
+        ...(c.url ? { url: c.url } : {}),
+        ...(review ? { reviewId: review.id } : {}),
+        ...(asReviewState(review?.state) ? { reviewState: asReviewState(review?.state) } : {}),
+        isPending: c.state === 'PENDING' || review?.state === 'PENDING',
+        isMine: c.author?.login === viewerLogin,
+    };
+}
+export function mapThread(t, comments) {
+    return {
+        id: t.id,
+        path: t.path,
+        line: t.line,
+        startLine: t.startLine,
+        side: asSide(t.diffSide),
+        startSide: asOptionalSide(t.startDiffSide),
+        originalLine: t.originalLine,
+        isResolved: t.isResolved,
+        isOutdated: t.isOutdated,
+        comments,
+    };
+}
+/**
+ * The Overview conversation: issue comments plus submitted reviews, oldest
+ * first. The viewer's PENDING review is excluded (it is not public), and so
+ * are reviews that carry neither a body nor inline comments (pure approvals
+ * still have a state and are kept).
+ */
+export function buildConversation(comments, reviews) {
+    const items = [];
+    for (const c of comments) {
+        items.push({
+            at: Date.parse(c.createdAt),
+            item: {
+                kind: 'comment',
+                id: c.id,
+                author: mapActor(c.author),
+                body: c.body,
+                bodyHTML: c.bodyHTML,
+                createdAt: c.createdAt,
+                ...(c.url ? { url: c.url } : {}),
+            },
+        });
+    }
+    for (const r of reviews) {
+        if (r.state === 'PENDING')
+            continue;
+        const commentCount = r.comments?.totalCount ?? 0;
+        if (r.body.trim() === '' && commentCount === 0 && r.state === 'COMMENTED')
+            continue;
+        items.push({
+            at: Date.parse(r.submittedAt ?? r.createdAt),
+            item: {
+                kind: 'review',
+                id: r.id,
+                author: mapActor(r.author),
+                body: r.body,
+                bodyHTML: r.bodyHTML,
+                state: asReviewState(r.state) ?? 'COMMENTED',
+                submittedAt: r.submittedAt,
+                ...(r.url ? { url: r.url } : {}),
+                commentCount,
+            },
+        });
+    }
+    items.sort((a, b) => a.at - b.at);
+    return items.map((x) => x.item);
+}
+const noop = () => { };
+/** GitHub owner and repository names are case-insensitive. */
+const sameSlug = (a, b) => a.toLowerCase() === b.toLowerCase();
+const notInPullRequest = (what) => new HttpError(404, `${what} not found in this pull request`, 'not_found');
+const repoNotFound = (repo) => new ForgeError(`Repository ${repo.owner}/${repo.repo} was not found on GitHub.`, 404);
+const prNotFound = (repo, number) => new ForgeError(`Pull request #${number} was not found in ${repo.owner}/${repo.repo}.`, 404);
+// ---------------------------------------------------------------------------
+// Search-query building (GitHub search API qualifiers)
+// ---------------------------------------------------------------------------
+/** Logins are safe bare; anything else gets quoted so `/` and `:` stay literal. */
+const SAFE_BARE = /^[A-Za-z0-9_.-]+$/;
+const quote = (value) => SAFE_BARE.test(value) ? value : `"${value.replace(/"/g, '')}"`;
+/**
+ * The search string for a filter: `repo:o/r is:pr is:open` plus qualifiers.
+ * Title text is passed as tokens with `in:title`; text containing `:` or
+ * quotes becomes a quoted phrase so it can never inject qualifiers. A bare
+ * hex token doubles as a commit-SHA search, which GitHub handles natively.
+ */
+export function buildSearchQuery(repo, filter) {
+    const parts = [`repo:${repo.owner}/${repo.repo}`, 'is:pr', 'is:open'];
+    const text = filter?.text?.trim();
+    if (text) {
+        // A bare hex SHA must go WITHOUT `in:title`: GitHub matches it to the PR
+        // by commit instead. Text containing `:` or quotes becomes a phrase so it
+        // can never inject qualifiers.
+        if (/^[0-9a-f]{7,40}$/i.test(text)) {
+            parts.push(text.toLowerCase());
+        }
+        else {
+            const safe = /["':]/.test(text) ? `"${text.replace(/"/g, '')}"` : text;
+            parts.push(`${safe} in:title`);
+        }
+    }
+    const author = filter?.author?.trim();
+    if (author)
+        parts.push(`author:${quote(author)}`);
+    const head = filter?.head?.trim();
+    if (head)
+        parts.push(`head:${quote(head)}`);
+    const base = filter?.base?.trim();
+    if (base)
+        parts.push(`base:${quote(base)}`);
+    if (filter?.draft !== undefined)
+        parts.push(`draft:${filter.draft ? 'true' : 'false'}`);
+    return parts.join(' ');
+}
+/** Cache key: repo plus the filter's own identity (stable field order). */
+export function filterKey(repo, filter) {
+    if (filter === undefined || isEmptyFilter(filter))
+        return `${repo.owner}/${repo.repo}`;
+    const f = filter;
+    return [
+        `${repo.owner}/${repo.repo}`,
+        f.text ?? '',
+        f.author ?? '',
+        f.head ?? '',
+        f.base ?? '',
+        f.draft === undefined ? '' : String(f.draft),
+    ].join('|');
+}