@reviewflow/sdk 6.21.0 → 6.23.0

package/build/index-browser.es.js

@@ -1023,9 +1023,7 @@ const restComment = (comment) => ({
   line: comment.line,
   side: comment.side,
   ...comment.startLine === null || comment.startSide === null ? {} : {
-    // eslint-disable-next-line camelcase -- GitHub's field name
     start_line: comment.startLine,
-    // eslint-disable-next-line camelcase -- GitHub's field name
     start_side: comment.startSide
   }
 });
@@ -1091,7 +1089,6 @@ const editPullRequest = async (transport, { ownerRepo, number, edit }, options =
         await transport.rest({
           method: "POST",
           path: `${pullPath}/requested_reviewers`,
-          // eslint-disable-next-line camelcase -- GitHub's field name
           body: { reviewers: edit.add, team_reviewers: edit.addTeams }
         });
       }
@@ -1099,7 +1096,6 @@ const editPullRequest = async (transport, { ownerRepo, number, edit }, options =
         await transport.rest({
           method: "DELETE",
           path: `${pullPath}/requested_reviewers`,
-          // eslint-disable-next-line camelcase -- GitHub's field name
           body: { reviewers: edit.remove, team_reviewers: edit.removeTeams }
         });
       }
@@ -1147,13 +1143,10 @@ const editPullRequest = async (transport, { ownerRepo, number, edit }, options =
         method: "PUT",
         path: `${pullPath}/merge`,
         body: {
-          // eslint-disable-next-line camelcase -- GitHub's field name
           merge_method: edit.method,
           sha: edit.expectedHeadSha,
           ...edit.commitMessage === void 0 ? {} : {
-            // eslint-disable-next-line camelcase -- GitHub's field name
             commit_title: edit.commitMessage.title,
-            // eslint-disable-next-line camelcase -- GitHub's field name
             commit_message: edit.commitMessage.body
           }
         }
@@ -1164,7 +1157,6 @@ const editPullRequest = async (transport, { ownerRepo, number, edit }, options =
       await transport.rest({
         method: "PUT",
         path: `${pullPath}/update-branch`,
-        // eslint-disable-next-line camelcase -- GitHub's field name
         body: { expected_head_sha: edit.expectedHeadSha }
       });
       return null;
@@ -1244,7 +1236,6 @@ const editPullRequest = async (transport, { ownerRepo, number, edit }, options =
         method: "POST",
         path: `${pullPath}/reviews`,
         body: {
-          // eslint-disable-next-line camelcase -- GitHub's field name
           commit_id: edit.commitId,
           ...edit.body === "" ? {} : { body: edit.body },
           event: reviewEventNames[edit.event],
@@ -1264,7 +1255,6 @@ const editPullRequest = async (transport, { ownerRepo, number, edit }, options =
       await transport.rest({
         method: "POST",
         path: `${pullPath}/comments`,
-        // eslint-disable-next-line camelcase -- GitHub's field name
         body: { commit_id: edit.commitId, ...restComment(edit.comment) }
       });
       return null;
@@ -2317,6 +2307,75 @@ const createGitHubTransport = (send) => ({
   }
 });
 
+const prStatuses = [
+  "approved",
+  "changesRequested",
+  "closed",
+  "draft",
+  "merged",
+  "noReviewers",
+  "waitingReview"
+];
+const reviewStatuses = {
+  approved: "approved",
+  changesRequested: "changesRequested",
+  reviewRequired: "waitingReview"
+};
+const prStatus = ({
+  state,
+  reviewDecision
+}) => {
+  if (state !== "open") return state;
+  return reviewDecision === null ? "noReviewers" : reviewStatuses[reviewDecision];
+};
+const prStatusLabels = {
+  approved: "approved",
+  changesRequested: "changes requested",
+  closed: "closed",
+  draft: "draft",
+  merged: "merged",
+  noReviewers: "no reviewers",
+  waitingReview: "waiting review"
+};
+const prHasConflicts = ({
+  state,
+  mergeable
+}) => (state === "open" || state === "draft") && mergeable === "conflicting";
+const prUrl = (ownerRepo, number) => `https://github.com/${ownerRepo}/pull/${String(number)}`;
+const prNumberPattern = /^#?(\d+)$/;
+const prUrlPattern = /^https?:\/\/github\.com\/([^/\s]+\/[^/\s]+)\/pull\/(\d+)(?:[/?#]\S*)?$/i;
+const prNumberOf = (input, ownerRepo) => {
+  const text = input.trim();
+  const url = prUrlPattern.exec(text);
+  const [, digits] = url === null ? prNumberPattern.exec(text) ?? [] : [];
+  if (url !== null && url[1]?.toLowerCase() !== ownerRepo.toLowerCase()) {
+    return `that pull request is not in ${ownerRepo}`;
+  }
+  const number = Number(url?.[2] ?? digits);
+  if (!Number.isInteger(number) || number < 1) {
+    return "a pull request number or its GitHub link is expected";
+  }
+  return number;
+};
+const reviewflowReviewDecisions = {
+  approved: "approved",
+  changesRequested: "changesRequested",
+  requested: "reviewRequired",
+  none: null
+};
+const reviewflowPrStatus = ({
+  state,
+  reviewState
+}) => {
+  if (state === null) return null;
+  if (state !== "open") return state;
+  if (reviewState === null) return null;
+  return prStatus({
+    state,
+    reviewDecision: reviewflowReviewDecisions[reviewState]
+  });
+};
+
 const pullRequestParts = [
   "detail",
   "checks",
@@ -2401,6 +2460,32 @@ const pullRequestEditMovesBoard = (edit) => {
   }
 };
 
+const dayMs = 24 * 60 * 60 * 1e3;
+const weekdayReach = 6;
+const startOfDay = (date) => new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+const calendarDaysAgo = (date, now) => Math.round((startOfDay(now) - startOfDay(date)) / dayMs);
+const formatRelativeDate = (value, { now = /* @__PURE__ */ new Date(), locale } = {}) => {
+  const date = typeof value === "string" ? new Date(value) : value;
+  if (Number.isNaN(date.getTime())) return "unknown date";
+  const time = date.toLocaleTimeString(locale, {
+    hour: "2-digit",
+    minute: "2-digit"
+  });
+  const days = calendarDaysAgo(date, now);
+  if (days === 0) return `today ${time}`;
+  if (days === 1) return `yesterday ${time}`;
+  if (days > 1 && days <= weekdayReach) {
+    const weekday = date.toLocaleDateString("en", { weekday: "long" });
+    return `last ${weekday} ${time}`;
+  }
+  const day = date.toLocaleDateString(locale, {
+    day: "numeric",
+    month: "short",
+    ...date.getFullYear() === now.getFullYear() ? {} : { year: "numeric" }
+  });
+  return `${day}, ${time}`;
+};
+
 const partFields = {
   detail: (pr) => [
     pr.title,
@@ -3074,6 +3159,92 @@ const applyStreamEvent = (snapshot, event) => {
   };
 };
 
+const maxFailedCheckNames = 9;
+const bucketsSilentOnPassedChecks = /* @__PURE__ */ new Set(["changes-requested", "drafts"]);
+const reRequestedBucket = "re-requested-reviews";
+const requestingAttentionGroup = "requesting-attention";
+const counted = (count, one, many) => `${String(count)} ${count === 1 ? one : many}`;
+const people = (logins, viewer) => logins.map((login) => login === viewer ? "you" : `@${login}`).join(", ");
+const failedChecksText = ({
+  checksConclusion,
+  failedChecks
+}) => {
+  if (failedChecks.length === 0) {
+    return checksConclusion === "failed" ? "checks failed" : null;
+  }
+  const names = failedChecks.slice(0, maxFailedCheckNames).join(", ");
+  const remaining = failedChecks.length - maxFailedCheckNames;
+  const more = remaining > 0 ? ` +${String(remaining)}` : "";
+  return `${failedChecks.length === 1 ? "check" : "checks"} failed: ${names}${more}`;
+};
+const reviewflowPrFailure = (pr) => {
+  const parts = [
+    failedChecksText(pr),
+    pr.lintFailed ? "pr lint failed" : null,
+    pr.mergeable === "conflicting" ? "conflicts" : null
+  ].filter((part) => part !== null);
+  return parts.length === 0 ? null : parts.join(" \xB7 ");
+};
+const reviewflowPrChangesRequested = ({ changesRequestedBy }, viewer) => changesRequestedBy.length === 0 ? null : `changes requested by ${people(changesRequestedBy, viewer)}`;
+const checksProgressText = ({
+  checksConclusion,
+  checksRunning
+}, bucketKey) => {
+  if (checksRunning > 0) {
+    return `${counted(checksRunning, "check", "checks")} running`;
+  }
+  return checksConclusion === "passed" && !bucketsSilentOnPassedChecks.has(bucketKey) ? "checks passed" : null;
+};
+const awaitedText = ({
+  requestedReviewers,
+  reRequestedReviewers,
+  requestedTeams
+}, { bucketKey, groupKey, viewer }) => {
+  const reviewers = [
+    ...requestedReviewers,
+    ...bucketKey === reRequestedBucket ? [] : reRequestedReviewers
+  ];
+  if (reviewers.length === 0 && requestedTeams.length === 0) return null;
+  const verb = groupKey === requestingAttentionGroup ? "requested" : "awaiting";
+  const awaited = [
+    ...reviewers.length === 0 ? [] : [people(reviewers, viewer)],
+    ...requestedTeams.map((team) => `#${team}`)
+  ];
+  return `${verb} ${awaited.join(", ")}`;
+};
+const reviewflowPrProgress = (pr, context) => {
+  const parts = [
+    checksProgressText(pr, context.bucketKey),
+    pr.approvedBy.length === 0 ? null : `approved by ${people(pr.approvedBy, context.viewer)}`,
+    pr.unresolvedThreads ? counted(pr.unresolvedThreads, "unresolved thread", "unresolved threads") : null,
+    awaitedText(pr, context)
+  ].filter((part) => part !== null);
+  return parts.length === 0 ? null : parts.join(" \xB7 ");
+};
+const reviewflowPrOwners = ({ author, assignees }, viewer) => {
+  const named = [...author === null ? [] : [author], ...assignees];
+  if (named.length === 0) return null;
+  if (viewer !== null && named.every((login) => login === viewer)) return null;
+  const byline = author === null ? null : `by ${people([author], viewer)}`;
+  if (assignees.length === 0) return byline;
+  const assignment = `assigned to ${people(assignees, viewer)}`;
+  if (author === null || !assignees.includes(author)) {
+    return byline === null ? assignment : `${byline} \xB7 ${assignment}`;
+  }
+  return assignees.length === 1 ? byline : assignment;
+};
+const reviewflowPrFlowDate = ({ openedAt, approvedAt }, options) => {
+  if (approvedAt !== null) {
+    return `approved ${formatRelativeDate(approvedAt, options)}`;
+  }
+  return openedAt === null ? null : `opened ${formatRelativeDate(openedAt, options)}`;
+};
+const formatPrChanges = ({
+  changedFiles,
+  additions,
+  deletions
+}) => `${counted(changedFiles, "file", "files")} +${String(additions)} \u2212${String(deletions)}`;
+
 const lingerMs = 5 * 6e4;
 const boardReadDelayMs = 3e3;
 const reconnectDelayMs = 1e3;
@@ -3334,5 +3505,5 @@ const insertCheckoutEntry = (source, ownerRepo) => {
   return { source: text, cursor: value };
 };
 
-export { accountOfOwnerRepo, applyPullRequestEdit, applyStreamEvent, applySuggestionsToText, assembleBoard, boardReadDelayMs, buildPrQuery, changedPullRequestParts, checkOutcomes, checksFromReviewflow, coAuthorTrailers, commitSuggestions, createGitHubTransport, createReviewflowClient, createReviewflowFollower, diffLines, diffPaths, diffThemeNames, diffThemeOptions, diffThemes, editPullRequest, fail, fetchCompareDiff, fetchPullRequestCandidates, fetchPullRequestHead, fetchPullRequestPart, fetchPullRequestRevisions, insertCheckoutEntry, interpretGraphql, isAttachablePath, isDiffTheme, isDiffWhitespace, isPullRequestOnBoard, isPullRequestPart, isPullRequestReactionContent, isReviewflowFailure, lingerMs, maxExtraPagesPerBucket, maxLookupTargets, maxRetryMs, parsePrQueryResponse, parsePullRequestCandidates, parsePullRequestChecks, parsePullRequestCommits, parsePullRequestDetail, parsePullRequestEdit, parsePullRequestFiles, parsePullRequestRevisions, parsePullRequestTimeline, parseSuggestions, partFingerprint, planSuggestions, prFields, pullRequestCandidatesQuery, pullRequestChecksQuery, pullRequestCommitsQuery, pullRequestDetailQuery, pullRequestEditMovesBoard, pullRequestFilesQuery, pullRequestHeadQuery, pullRequestParts, pullRequestPartsStaleAfter, pullRequestReactionContents, pullRequestRevisionsQuery, pullRequestTimelineQuery, readAccountBoards, readPrDetail, readReviewflowStream, reconnectDelayMs, responseFailure, restErrorMessage, reviewflowErrorCode, splitOwnerRepo, streamClosedWithinDays, streamIdleTimeoutMs, subjectsOf, suggestionCommitRefusal, suggestionOriginalLines, suggestionRangesOverlap, toBoardPr, toFetchedPr, withAccountBoard, withFileViewed };
+export { accountOfOwnerRepo, applyPullRequestEdit, applyStreamEvent, applySuggestionsToText, assembleBoard, boardReadDelayMs, buildPrQuery, changedPullRequestParts, checkOutcomes, checksFromReviewflow, coAuthorTrailers, commitSuggestions, createGitHubTransport, createReviewflowClient, createReviewflowFollower, diffLines, diffPaths, diffThemeNames, diffThemeOptions, diffThemes, editPullRequest, fail, fetchCompareDiff, fetchPullRequestCandidates, fetchPullRequestHead, fetchPullRequestPart, fetchPullRequestRevisions, formatPrChanges, formatRelativeDate, insertCheckoutEntry, interpretGraphql, isAttachablePath, isDiffTheme, isDiffWhitespace, isPullRequestOnBoard, isPullRequestPart, isPullRequestReactionContent, isReviewflowFailure, lingerMs, maxExtraPagesPerBucket, maxFailedCheckNames, maxLookupTargets, maxRetryMs, parsePrQueryResponse, parsePullRequestCandidates, parsePullRequestChecks, parsePullRequestCommits, parsePullRequestDetail, parsePullRequestEdit, parsePullRequestFiles, parsePullRequestRevisions, parsePullRequestTimeline, parseSuggestions, partFingerprint, planSuggestions, prFields, prHasConflicts, prNumberOf, prStatus, prStatusLabels, prStatuses, prUrl, pullRequestCandidatesQuery, pullRequestChecksQuery, pullRequestCommitsQuery, pullRequestDetailQuery, pullRequestEditMovesBoard, pullRequestFilesQuery, pullRequestHeadQuery, pullRequestParts, pullRequestPartsStaleAfter, pullRequestReactionContents, pullRequestRevisionsQuery, pullRequestTimelineQuery, readAccountBoards, readPrDetail, readReviewflowStream, reconnectDelayMs, responseFailure, restErrorMessage, reviewflowErrorCode, reviewflowPrChangesRequested, reviewflowPrFailure, reviewflowPrFlowDate, reviewflowPrOwners, reviewflowPrProgress, reviewflowPrStatus, reviewflowReviewDecisions, splitOwnerRepo, streamClosedWithinDays, streamIdleTimeoutMs, subjectsOf, suggestionCommitRefusal, suggestionOriginalLines, suggestionRangesOverlap, toBoardPr, toFetchedPr, withAccountBoard, withFileViewed };
 //# sourceMappingURL=index-browser.es.js.map

package/build/index-node.mjs

@@ -1023,9 +1023,7 @@ const restComment = (comment) => ({
   line: comment.line,
   side: comment.side,
   ...comment.startLine === null || comment.startSide === null ? {} : {
-    // eslint-disable-next-line camelcase -- GitHub's field name
     start_line: comment.startLine,
-    // eslint-disable-next-line camelcase -- GitHub's field name
     start_side: comment.startSide
   }
 });
@@ -1091,7 +1089,6 @@ const editPullRequest = async (transport, { ownerRepo, number, edit }, options =
         await transport.rest({
           method: "POST",
           path: `${pullPath}/requested_reviewers`,
-          // eslint-disable-next-line camelcase -- GitHub's field name
           body: { reviewers: edit.add, team_reviewers: edit.addTeams }
         });
       }
@@ -1099,7 +1096,6 @@ const editPullRequest = async (transport, { ownerRepo, number, edit }, options =
         await transport.rest({
           method: "DELETE",
           path: `${pullPath}/requested_reviewers`,
-          // eslint-disable-next-line camelcase -- GitHub's field name
           body: { reviewers: edit.remove, team_reviewers: edit.removeTeams }
         });
       }
@@ -1147,13 +1143,10 @@ const editPullRequest = async (transport, { ownerRepo, number, edit }, options =
         method: "PUT",
         path: `${pullPath}/merge`,
         body: {
-          // eslint-disable-next-line camelcase -- GitHub's field name
           merge_method: edit.method,
           sha: edit.expectedHeadSha,
           ...edit.commitMessage === void 0 ? {} : {
-            // eslint-disable-next-line camelcase -- GitHub's field name
             commit_title: edit.commitMessage.title,
-            // eslint-disable-next-line camelcase -- GitHub's field name
             commit_message: edit.commitMessage.body
           }
         }
@@ -1164,7 +1157,6 @@ const editPullRequest = async (transport, { ownerRepo, number, edit }, options =
       await transport.rest({
         method: "PUT",
         path: `${pullPath}/update-branch`,
-        // eslint-disable-next-line camelcase -- GitHub's field name
         body: { expected_head_sha: edit.expectedHeadSha }
       });
       return null;
@@ -1244,7 +1236,6 @@ const editPullRequest = async (transport, { ownerRepo, number, edit }, options =
         method: "POST",
         path: `${pullPath}/reviews`,
         body: {
-          // eslint-disable-next-line camelcase -- GitHub's field name
           commit_id: edit.commitId,
           ...edit.body === "" ? {} : { body: edit.body },
           event: reviewEventNames[edit.event],
@@ -1264,7 +1255,6 @@ const editPullRequest = async (transport, { ownerRepo, number, edit }, options =
       await transport.rest({
         method: "POST",
         path: `${pullPath}/comments`,
-        // eslint-disable-next-line camelcase -- GitHub's field name
         body: { commit_id: edit.commitId, ...restComment(edit.comment) }
       });
       return null;
@@ -2317,6 +2307,75 @@ const createGitHubTransport = (send) => ({
   }
 });
 
+const prStatuses = [
+  "approved",
+  "changesRequested",
+  "closed",
+  "draft",
+  "merged",
+  "noReviewers",
+  "waitingReview"
+];
+const reviewStatuses = {
+  approved: "approved",
+  changesRequested: "changesRequested",
+  reviewRequired: "waitingReview"
+};
+const prStatus = ({
+  state,
+  reviewDecision
+}) => {
+  if (state !== "open") return state;
+  return reviewDecision === null ? "noReviewers" : reviewStatuses[reviewDecision];
+};
+const prStatusLabels = {
+  approved: "approved",
+  changesRequested: "changes requested",
+  closed: "closed",
+  draft: "draft",
+  merged: "merged",
+  noReviewers: "no reviewers",
+  waitingReview: "waiting review"
+};
+const prHasConflicts = ({
+  state,
+  mergeable
+}) => (state === "open" || state === "draft") && mergeable === "conflicting";
+const prUrl = (ownerRepo, number) => `https://github.com/${ownerRepo}/pull/${String(number)}`;
+const prNumberPattern = /^#?(\d+)$/;
+const prUrlPattern = /^https?:\/\/github\.com\/([^/\s]+\/[^/\s]+)\/pull\/(\d+)(?:[/?#]\S*)?$/i;
+const prNumberOf = (input, ownerRepo) => {
+  const text = input.trim();
+  const url = prUrlPattern.exec(text);
+  const [, digits] = url === null ? prNumberPattern.exec(text) ?? [] : [];
+  if (url !== null && url[1]?.toLowerCase() !== ownerRepo.toLowerCase()) {
+    return `that pull request is not in ${ownerRepo}`;
+  }
+  const number = Number(url?.[2] ?? digits);
+  if (!Number.isInteger(number) || number < 1) {
+    return "a pull request number or its GitHub link is expected";
+  }
+  return number;
+};
+const reviewflowReviewDecisions = {
+  approved: "approved",
+  changesRequested: "changesRequested",
+  requested: "reviewRequired",
+  none: null
+};
+const reviewflowPrStatus = ({
+  state,
+  reviewState
+}) => {
+  if (state === null) return null;
+  if (state !== "open") return state;
+  if (reviewState === null) return null;
+  return prStatus({
+    state,
+    reviewDecision: reviewflowReviewDecisions[reviewState]
+  });
+};
+
 const pullRequestParts = [
   "detail",
   "checks",
@@ -2401,6 +2460,32 @@ const pullRequestEditMovesBoard = (edit) => {
   }
 };
 
+const dayMs = 24 * 60 * 60 * 1e3;
+const weekdayReach = 6;
+const startOfDay = (date) => new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+const calendarDaysAgo = (date, now) => Math.round((startOfDay(now) - startOfDay(date)) / dayMs);
+const formatRelativeDate = (value, { now = /* @__PURE__ */ new Date(), locale } = {}) => {
+  const date = typeof value === "string" ? new Date(value) : value;
+  if (Number.isNaN(date.getTime())) return "unknown date";
+  const time = date.toLocaleTimeString(locale, {
+    hour: "2-digit",
+    minute: "2-digit"
+  });
+  const days = calendarDaysAgo(date, now);
+  if (days === 0) return `today ${time}`;
+  if (days === 1) return `yesterday ${time}`;
+  if (days > 1 && days <= weekdayReach) {
+    const weekday = date.toLocaleDateString("en", { weekday: "long" });
+    return `last ${weekday} ${time}`;
+  }
+  const day = date.toLocaleDateString(locale, {
+    day: "numeric",
+    month: "short",
+    ...date.getFullYear() === now.getFullYear() ? {} : { year: "numeric" }
+  });
+  return `${day}, ${time}`;
+};
+
 const partFields = {
   detail: (pr) => [
     pr.title,
@@ -3074,6 +3159,92 @@ const applyStreamEvent = (snapshot, event) => {
   };
 };
 
+const maxFailedCheckNames = 9;
+const bucketsSilentOnPassedChecks = /* @__PURE__ */ new Set(["changes-requested", "drafts"]);
+const reRequestedBucket = "re-requested-reviews";
+const requestingAttentionGroup = "requesting-attention";
+const counted = (count, one, many) => `${String(count)} ${count === 1 ? one : many}`;
+const people = (logins, viewer) => logins.map((login) => login === viewer ? "you" : `@${login}`).join(", ");
+const failedChecksText = ({
+  checksConclusion,
+  failedChecks
+}) => {
+  if (failedChecks.length === 0) {
+    return checksConclusion === "failed" ? "checks failed" : null;
+  }
+  const names = failedChecks.slice(0, maxFailedCheckNames).join(", ");
+  const remaining = failedChecks.length - maxFailedCheckNames;
+  const more = remaining > 0 ? ` +${String(remaining)}` : "";
+  return `${failedChecks.length === 1 ? "check" : "checks"} failed: ${names}${more}`;
+};
+const reviewflowPrFailure = (pr) => {
+  const parts = [
+    failedChecksText(pr),
+    pr.lintFailed ? "pr lint failed" : null,
+    pr.mergeable === "conflicting" ? "conflicts" : null
+  ].filter((part) => part !== null);
+  return parts.length === 0 ? null : parts.join(" \xB7 ");
+};
+const reviewflowPrChangesRequested = ({ changesRequestedBy }, viewer) => changesRequestedBy.length === 0 ? null : `changes requested by ${people(changesRequestedBy, viewer)}`;
+const checksProgressText = ({
+  checksConclusion,
+  checksRunning
+}, bucketKey) => {
+  if (checksRunning > 0) {
+    return `${counted(checksRunning, "check", "checks")} running`;
+  }
+  return checksConclusion === "passed" && !bucketsSilentOnPassedChecks.has(bucketKey) ? "checks passed" : null;
+};
+const awaitedText = ({
+  requestedReviewers,
+  reRequestedReviewers,
+  requestedTeams
+}, { bucketKey, groupKey, viewer }) => {
+  const reviewers = [
+    ...requestedReviewers,
+    ...bucketKey === reRequestedBucket ? [] : reRequestedReviewers
+  ];
+  if (reviewers.length === 0 && requestedTeams.length === 0) return null;
+  const verb = groupKey === requestingAttentionGroup ? "requested" : "awaiting";
+  const awaited = [
+    ...reviewers.length === 0 ? [] : [people(reviewers, viewer)],
+    ...requestedTeams.map((team) => `#${team}`)
+  ];
+  return `${verb} ${awaited.join(", ")}`;
+};
+const reviewflowPrProgress = (pr, context) => {
+  const parts = [
+    checksProgressText(pr, context.bucketKey),
+    pr.approvedBy.length === 0 ? null : `approved by ${people(pr.approvedBy, context.viewer)}`,
+    pr.unresolvedThreads ? counted(pr.unresolvedThreads, "unresolved thread", "unresolved threads") : null,
+    awaitedText(pr, context)
+  ].filter((part) => part !== null);
+  return parts.length === 0 ? null : parts.join(" \xB7 ");
+};
+const reviewflowPrOwners = ({ author, assignees }, viewer) => {
+  const named = [...author === null ? [] : [author], ...assignees];
+  if (named.length === 0) return null;
+  if (viewer !== null && named.every((login) => login === viewer)) return null;
+  const byline = author === null ? null : `by ${people([author], viewer)}`;
+  if (assignees.length === 0) return byline;
+  const assignment = `assigned to ${people(assignees, viewer)}`;
+  if (author === null || !assignees.includes(author)) {
+    return byline === null ? assignment : `${byline} \xB7 ${assignment}`;
+  }
+  return assignees.length === 1 ? byline : assignment;
+};
+const reviewflowPrFlowDate = ({ openedAt, approvedAt }, options) => {
+  if (approvedAt !== null) {
+    return `approved ${formatRelativeDate(approvedAt, options)}`;
+  }
+  return openedAt === null ? null : `opened ${formatRelativeDate(openedAt, options)}`;
+};
+const formatPrChanges = ({
+  changedFiles,
+  additions,
+  deletions
+}) => `${counted(changedFiles, "file", "files")} +${String(additions)} \u2212${String(deletions)}`;
+
 const lingerMs = 5 * 6e4;
 const boardReadDelayMs = 3e3;
 const reconnectDelayMs = 1e3;
@@ -3334,5 +3505,5 @@ const insertCheckoutEntry = (source, ownerRepo) => {
   return { source: text, cursor: value };
 };
 
-export { accountOfOwnerRepo, applyPullRequestEdit, applyStreamEvent, applySuggestionsToText, assembleBoard, boardReadDelayMs, buildPrQuery, changedPullRequestParts, checkOutcomes, checksFromReviewflow, coAuthorTrailers, commitSuggestions, createGitHubTransport, createReviewflowClient, createReviewflowFollower, diffLines, diffPaths, diffThemeNames, diffThemeOptions, diffThemes, editPullRequest, fail, fetchCompareDiff, fetchPullRequestCandidates, fetchPullRequestHead, fetchPullRequestPart, fetchPullRequestRevisions, insertCheckoutEntry, interpretGraphql, isAttachablePath, isDiffTheme, isDiffWhitespace, isPullRequestOnBoard, isPullRequestPart, isPullRequestReactionContent, isReviewflowFailure, lingerMs, maxExtraPagesPerBucket, maxLookupTargets, maxRetryMs, parsePrQueryResponse, parsePullRequestCandidates, parsePullRequestChecks, parsePullRequestCommits, parsePullRequestDetail, parsePullRequestEdit, parsePullRequestFiles, parsePullRequestRevisions, parsePullRequestTimeline, parseSuggestions, partFingerprint, planSuggestions, prFields, pullRequestCandidatesQuery, pullRequestChecksQuery, pullRequestCommitsQuery, pullRequestDetailQuery, pullRequestEditMovesBoard, pullRequestFilesQuery, pullRequestHeadQuery, pullRequestParts, pullRequestPartsStaleAfter, pullRequestReactionContents, pullRequestRevisionsQuery, pullRequestTimelineQuery, readAccountBoards, readPrDetail, readReviewflowStream, reconnectDelayMs, responseFailure, restErrorMessage, reviewflowErrorCode, splitOwnerRepo, streamClosedWithinDays, streamIdleTimeoutMs, subjectsOf, suggestionCommitRefusal, suggestionOriginalLines, suggestionRangesOverlap, toBoardPr, toFetchedPr, withAccountBoard, withFileViewed };
+export { accountOfOwnerRepo, applyPullRequestEdit, applyStreamEvent, applySuggestionsToText, assembleBoard, boardReadDelayMs, buildPrQuery, changedPullRequestParts, checkOutcomes, checksFromReviewflow, coAuthorTrailers, commitSuggestions, createGitHubTransport, createReviewflowClient, createReviewflowFollower, diffLines, diffPaths, diffThemeNames, diffThemeOptions, diffThemes, editPullRequest, fail, fetchCompareDiff, fetchPullRequestCandidates, fetchPullRequestHead, fetchPullRequestPart, fetchPullRequestRevisions, formatPrChanges, formatRelativeDate, insertCheckoutEntry, interpretGraphql, isAttachablePath, isDiffTheme, isDiffWhitespace, isPullRequestOnBoard, isPullRequestPart, isPullRequestReactionContent, isReviewflowFailure, lingerMs, maxExtraPagesPerBucket, maxFailedCheckNames, maxLookupTargets, maxRetryMs, parsePrQueryResponse, parsePullRequestCandidates, parsePullRequestChecks, parsePullRequestCommits, parsePullRequestDetail, parsePullRequestEdit, parsePullRequestFiles, parsePullRequestRevisions, parsePullRequestTimeline, parseSuggestions, partFingerprint, planSuggestions, prFields, prHasConflicts, prNumberOf, prStatus, prStatusLabels, prStatuses, prUrl, pullRequestCandidatesQuery, pullRequestChecksQuery, pullRequestCommitsQuery, pullRequestDetailQuery, pullRequestEditMovesBoard, pullRequestFilesQuery, pullRequestHeadQuery, pullRequestParts, pullRequestPartsStaleAfter, pullRequestReactionContents, pullRequestRevisionsQuery, pullRequestTimelineQuery, readAccountBoards, readPrDetail, readReviewflowStream, reconnectDelayMs, responseFailure, restErrorMessage, reviewflowErrorCode, reviewflowPrChangesRequested, reviewflowPrFailure, reviewflowPrFlowDate, reviewflowPrOwners, reviewflowPrProgress, reviewflowPrStatus, reviewflowReviewDecisions, splitOwnerRepo, streamClosedWithinDays, streamIdleTimeoutMs, subjectsOf, suggestionCommitRefusal, suggestionOriginalLines, suggestionRangesOverlap, toBoardPr, toFetchedPr, withAccountBoard, withFileViewed };
 //# sourceMappingURL=index-node.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reviewflow/sdk",
-  "version": "6.21.0",
+  "version": "6.23.0",
   "description": "pull request model shared by the reviewflow app server and its ui: diff and api types, pure utils, the GitHub layer behind an injected transport, and (node only) reading a diff from a local checkout (@reviewflow/sdk/git) and editing a text file in place (@reviewflow/sdk/files)",
   "keywords": [
     "code-review",
@@ -61,19 +61,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "pnpm run clean:build && rollup --config rollup.config.mjs",
-    "clean": "pnpm run clean:build",
-    "clean:build": "pob-esbuild-clean-out build",
-    "lint": "pnpm run lint:oxlint && pnpm run lint:eslint",
-    "lint:eslint": "pnpm --dir '../..' exec eslint --quiet 'packages/sdk'",
-    "lint:oxlint": "pnpm --dir '../..' exec oxlint --quiet 'packages/sdk'",
-    "start": "pnpm run clean:build && rollup --config rollup.config.mjs --watch",
-    "test": "pnpm run --dir '../..' test -- 'packages/sdk'",
-    "tsc": "tsrs",
-    "tsc:go": "tsc",
-    "watch": "pnpm run clean:build && rollup --config rollup.config.mjs --watch"
-  },
   "dependencies": {
     "oxc-parser": "0.127.0"
   },
@@ -134,5 +121,18 @@
       }
     ],
     "typescript": true
+  },
+  "scripts": {
+    "build": "pnpm run clean:build && rollup --config rollup.config.mjs",
+    "clean": "pnpm run clean:build",
+    "clean:build": "pob-esbuild-clean-out build",
+    "lint": "pnpm run lint:oxlint && pnpm run lint:eslint",
+    "lint:eslint": "pnpm --dir '../..' exec eslint --quiet 'packages/sdk'",
+    "lint:oxlint": "pnpm --dir '../..' exec oxlint --quiet 'packages/sdk'",
+    "start": "pnpm run clean:build && rollup --config rollup.config.mjs --watch",
+    "test": "pnpm run --dir '../..' test -- 'packages/sdk'",
+    "tsc": "tsrs",
+    "tsc:go": "tsc",
+    "watch": "pnpm run clean:build && rollup --config rollup.config.mjs --watch"
   }
-}
+}

package/src/index.ts

@@ -20,15 +20,18 @@ export type * from "./api/pullRequest.ts";
 export type * from "./types/entities.ts";
 export type * from "./types/ids.ts";
 export type * from "./types/reviewflow.ts";
+export * from "./utils/prStatus.ts";
 export * from "./utils/pullRequestEdit.ts";
 export * from "./utils/pullRequestPart.ts";
 export * from "./utils/pullRequestReaction.ts";
 export * from "./utils/pullRequestSuggestion.ts";
+export * from "./utils/relativeDate.ts";
 export * from "./reviewflow/changedParts.ts";
 export * from "./reviewflow/checksFromReviewflow.ts";
 export * from "./reviewflow/client.ts";
 export * from "./reviewflow/stream.ts";
 export * from "./reviewflow/board.ts";
+export * from "./reviewflow/boardFacts.ts";
 export * from "./reviewflow/follow.ts";
 export type * from "./reviewflow/status.ts";
 export { insertCheckoutEntry } from "./config/insertCheckoutEntry.ts";

package/src/reviewflow/boardFacts.ts

@@ -0,0 +1,184 @@
+import type { ReviewflowPrChanges } from "../types/reviewflow.ts";
+import type { FormatRelativeDateOptions } from "../utils/relativeDate.ts";
+import { formatRelativeDate } from "../utils/relativeDate.ts";
+import type { ReviewflowBoardPr } from "./board.ts";
+
+/**
+ * What reviewflow's own board row says about a pull request, in its wording so
+ * the two boards read the same. The status line comes in three parts by how
+ * loudly each is shown: what blocks the merge, changes requested, the rest.
+ */
+
+export const maxFailedCheckNames = 9;
+
+/** Where a row is shown, which decides what it leaves to its bucket's title. */
+export interface ReviewflowRowContext {
+  bucketKey: string;
+  groupKey: string;
+  /** the token's login, named "you" */
+  viewer: string | null;
+}
+
+/** the buckets whose title already says whether the checks pass */
+const bucketsSilentOnPassedChecks = new Set(["changes-requested", "drafts"]);
+/** the bucket whose title already says every reviewer was asked again */
+const reRequestedBucket = "re-requested-reviews";
+/** someone else's pull request requests a review, the operator's awaits one */
+const requestingAttentionGroup = "requesting-attention";
+
+const counted = (count: number, one: string, many: string): string =>
+  `${String(count)} ${count === 1 ? one : many}`;
+
+const people = (logins: string[], viewer: string | null): string =>
+  logins.map((login) => (login === viewer ? "you" : `@${login}`)).join(", ");
+
+const failedChecksText = ({
+  checksConclusion,
+  failedChecks,
+}: Pick<ReviewflowBoardPr, "checksConclusion" | "failedChecks">):
+  | string
+  | null => {
+  if (failedChecks.length === 0) {
+    return checksConclusion === "failed" ? "checks failed" : null;
+  }
+  const names = failedChecks.slice(0, maxFailedCheckNames).join(", ");
+  const remaining = failedChecks.length - maxFailedCheckNames;
+  const more = remaining > 0 ? ` +${String(remaining)}` : "";
+  return `${failedChecks.length === 1 ? "check" : "checks"} failed: ${names}${more}`;
+};
+
+/**
+ * Failing checks (after reviewflow's allowed-to-fail rules, by name), a failed
+ * pr lint and a merge conflict; null when nothing blocks.
+ */
+export const reviewflowPrFailure = (
+  pr: Pick<
+    ReviewflowBoardPr,
+    "checksConclusion" | "failedChecks" | "lintFailed" | "mergeable"
+  >,
+): string | null => {
+  const parts = [
+    failedChecksText(pr),
+    pr.lintFailed ? "pr lint failed" : null,
+    pr.mergeable === "conflicting" ? "conflicts" : null,
+  ].filter((part) => part !== null);
+  return parts.length === 0 ? null : parts.join(" · ");
+};
+
+export const reviewflowPrChangesRequested = (
+  { changesRequestedBy }: Pick<ReviewflowBoardPr, "changesRequestedBy">,
+  viewer: string | null,
+): string | null =>
+  changesRequestedBy.length === 0
+    ? null
+    : `changes requested by ${people(changesRequestedBy, viewer)}`;
+
+const checksProgressText = (
+  {
+    checksConclusion,
+    checksRunning,
+  }: Pick<ReviewflowBoardPr, "checksConclusion" | "checksRunning">,
+  bucketKey: string,
+): string | null => {
+  if (checksRunning > 0) {
+    return `${counted(checksRunning, "check", "checks")} running`;
+  }
+  return checksConclusion === "passed" &&
+    !bucketsSilentOnPassedChecks.has(bucketKey)
+    ? "checks passed"
+    : null;
+};
+
+const awaitedText = (
+  {
+    requestedReviewers,
+    reRequestedReviewers,
+    requestedTeams,
+  }: Pick<
+    ReviewflowBoardPr,
+    "requestedReviewers" | "requestedTeams" | "reRequestedReviewers"
+  >,
+  { bucketKey, groupKey, viewer }: ReviewflowRowContext,
+): string | null => {
+  const reviewers = [
+    ...requestedReviewers,
+    ...(bucketKey === reRequestedBucket ? [] : reRequestedReviewers),
+  ];
+  if (reviewers.length === 0 && requestedTeams.length === 0) return null;
+  const verb = groupKey === requestingAttentionGroup ? "requested" : "awaiting";
+  const awaited = [
+    ...(reviewers.length === 0 ? [] : [people(reviewers, viewer)]),
+    ...requestedTeams.map((team) => `#${team}`),
+  ];
+  return `${verb} ${awaited.join(", ")}`;
+};
+
+/** running or passed checks, approvals, open threads, awaited reviewers */
+export const reviewflowPrProgress = (
+  pr: Pick<
+    ReviewflowBoardPr,
+    | "approvedBy"
+    | "checksConclusion"
+    | "checksRunning"
+    | "requestedReviewers"
+    | "requestedTeams"
+    | "reRequestedReviewers"
+    | "unresolvedThreads"
+  >,
+  context: ReviewflowRowContext,
+): string | null => {
+  const parts = [
+    checksProgressText(pr, context.bucketKey),
+    pr.approvedBy.length === 0
+      ? null
+      : `approved by ${people(pr.approvedBy, context.viewer)}`,
+    pr.unresolvedThreads
+      ? counted(pr.unresolvedThreads, "unresolved thread", "unresolved threads")
+      : null,
+    awaitedText(pr, context),
+  ].filter((part) => part !== null);
+  return parts.length === 0 ? null : parts.join(" · ");
+};
+
+/**
+ * "by @author", "assigned to @a", or both. An author who is their own only
+ * assignee is a byline, not an assignment; a pull request whose only person is
+ * the viewer names nobody.
+ */
+export const reviewflowPrOwners = (
+  { author, assignees }: Pick<ReviewflowBoardPr, "assignees" | "author">,
+  viewer: string | null,
+): string | null => {
+  const named = [...(author === null ? [] : [author]), ...assignees];
+  if (named.length === 0) return null;
+  if (viewer !== null && named.every((login) => login === viewer)) return null;
+
+  const byline = author === null ? null : `by ${people([author], viewer)}`;
+  if (assignees.length === 0) return byline;
+  const assignment = `assigned to ${people(assignees, viewer)}`;
+
+  if (author === null || !assignees.includes(author)) {
+    return byline === null ? assignment : `${byline} · ${assignment}`;
+  }
+  // naming every assignee already names the author among them
+  return assignees.length === 1 ? byline : assignment;
+};
+
+export const reviewflowPrFlowDate = (
+  { openedAt, approvedAt }: Pick<ReviewflowBoardPr, "approvedAt" | "openedAt">,
+  options?: FormatRelativeDateOptions,
+): string | null => {
+  if (approvedAt !== null) {
+    return `approved ${formatRelativeDate(approvedAt, options)}`;
+  }
+  return openedAt === null
+    ? null
+    : `opened ${formatRelativeDate(openedAt, options)}`;
+};
+
+export const formatPrChanges = ({
+  changedFiles,
+  additions,
+  deletions,
+}: ReviewflowPrChanges): string =>
+  `${counted(changedFiles, "file", "files")} +${String(additions)} −${String(deletions)}`;

package/src/utils/prStatus.ts

@@ -0,0 +1,152 @@
+import type { ReviewflowBoardPr } from "../reviewflow/board.ts";
+import type {
+  PrMergeable,
+  PrReviewDecision,
+  PrState,
+} from "../types/entities.ts";
+import type { ReviewflowReviewState } from "../types/reviewflow.ts";
+
+/**
+ * What the operator is told about a pull request, in one word or two.
+ *
+ * `pr.state` and `pr.reviewDecision` are two columns because GitHub reports two
+ * fields, but they are never two answers: an open PR is only ever interesting
+ * for where its review stands, and "open" on its own says nothing the branch did
+ * not already say. So the two collapse into one status, and every surface
+ * reads it from here rather than
+ * formatting the columns itself. They had drifted into three different renderings
+ * of the same row.
+ *
+ * `noReviewers` and `waitingReview` are a real distinction, not a null check:
+ * GitHub leaves `reviewDecision` null when nothing is required and nobody was
+ * asked, and answers `REVIEW_REQUIRED` when a review is required and missing.
+ * The first is the operator's own omission — nobody is coming — and the second
+ * is somebody else's turn.
+ */
+export const prStatuses = [
+  "approved",
+  "changesRequested",
+  "closed",
+  "draft",
+  "merged",
+  "noReviewers",
+  "waitingReview",
+] as const;
+
+export type PrStatus = (typeof prStatuses)[number];
+
+const reviewStatuses: Record<
+  NonNullable<PrReviewDecision>,
+  Extract<PrStatus, "approved" | "changesRequested" | "waitingReview">
+> = {
+  approved: "approved",
+  changesRequested: "changesRequested",
+  reviewRequired: "waitingReview",
+};
+
+/**
+ * A closed or merged PR keeps its own status whatever the last review said: an
+ * approved PR that was closed is closed, and saying "approved" would describe a
+ * decision nobody is going to act on.
+ */
+export const prStatus = ({
+  state,
+  reviewDecision,
+}: {
+  state: PrState;
+  reviewDecision: PrReviewDecision;
+}): PrStatus => {
+  if (state !== "open") return state;
+  return reviewDecision === null
+    ? "noReviewers"
+    : reviewStatuses[reviewDecision];
+};
+
+export const prStatusLabels: Record<PrStatus, string> = {
+  approved: "approved",
+  changesRequested: "changes requested",
+  closed: "closed",
+  draft: "draft",
+  merged: "merged",
+  noReviewers: "no reviewers",
+  waitingReview: "waiting review",
+};
+
+/**
+ * Only while it can still be merged: GitHub keeps answering for a closed one,
+ * and a conflict nobody will resolve is not something to look at.
+ */
+export const prHasConflicts = ({
+  state,
+  mergeable,
+}: {
+  state: PrState;
+  mergeable: PrMergeable;
+}): boolean =>
+  (state === "open" || state === "draft") && mergeable === "conflicting";
+
+/**
+ * Built rather than stored: the number and `owner/repo` are kept apart,
+ * and a url column would be a third copy of both that goes stale when either
+ * moves. GitHub redirects `/pull/<n>` to the right kind of page, so nothing here
+ * has to know whether the number belongs to a PR or an issue.
+ */
+export const prUrl = (ownerRepo: string, number: number): string =>
+  `https://github.com/${ownerRepo}/pull/${String(number)}`;
+
+const prNumberPattern = /^#?(\d+)$/;
+const prUrlPattern =
+  /^https?:\/\/github\.com\/([^/\s]+\/[^/\s]+)\/pull\/(\d+)(?:[/?#]\S*)?$/i;
+
+/**
+ * A pull request of `ownerRepo` as the operator names one — `123`, `#123` or
+ * its GitHub url, a tab of it included — or why the text names none. A url of
+ * another repository is refused rather than reduced to its number, which would
+ * name a different pull request.
+ */
+export const prNumberOf = (
+  input: string,
+  ownerRepo: string,
+): number | string => {
+  const text = input.trim();
+  const url = prUrlPattern.exec(text);
+  const [, digits] = url === null ? (prNumberPattern.exec(text) ?? []) : [];
+  if (url !== null && url[1]?.toLowerCase() !== ownerRepo.toLowerCase()) {
+    return `that pull request is not in ${ownerRepo}`;
+  }
+  const number = Number(url?.[2] ?? digits);
+  if (!Number.isInteger(number) || number < 1) {
+    return "a pull request number or its GitHub link is expected";
+  }
+  return number;
+};
+
+/**
+ * reviewflow's review state in GitHub's vocabulary, which `pr` stores. `none` is
+ * what GitHub cannot say on a repository that requires a review: it answers
+ * `REVIEW_REQUIRED` whether or not anyone was asked, where reviewflow tells the
+ * two apart.
+ */
+export const reviewflowReviewDecisions: Record<
+  ReviewflowReviewState,
+  PrReviewDecision
+> = {
+  approved: "approved",
+  changesRequested: "changesRequested",
+  requested: "reviewRequired",
+  none: null,
+};
+
+/** null when reviewflow does not know enough to say */
+export const reviewflowPrStatus = ({
+  state,
+  reviewState,
+}: Pick<ReviewflowBoardPr, "reviewState" | "state">): PrStatus | null => {
+  if (state === null) return null;
+  if (state !== "open") return state;
+  if (reviewState === null) return null;
+  return prStatus({
+    state,
+    reviewDecision: reviewflowReviewDecisions[reviewState],
+  });
+};

package/src/utils/relativeDate.ts

@@ -0,0 +1,56 @@
+/**
+ * A past date the way the operator says it: "today 14:32", "yesterday 09:10",
+ * "last Monday 16:05", then "12 Oct, 14:32" — and the year once it is not this
+ * one. The boards read dates to answer "is this from this morning or last
+ * week", which a full timestamp makes them work out.
+ *
+ * Calendar days in the machine's own time zone, not 24-hour spans: 23:50
+ * yesterday is "yesterday" at 00:10. The time and the month follow the
+ * locale; the words are the app's, which is in English.
+ */
+
+const dayMs = 24 * 60 * 60 * 1000;
+
+/** how many days back the weekday alone still names the day without doubt */
+const weekdayReach = 6;
+
+const startOfDay = (date: Date): number =>
+  new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+
+/** Whole calendar days from `date` to `now`; negative for a future date. */
+const calendarDaysAgo = (date: Date, now: Date): number =>
+  Math.round((startOfDay(now) - startOfDay(date)) / dayMs);
+
+export interface FormatRelativeDateOptions {
+  now?: Date;
+  /** a BCP 47 tag; the runtime's own when absent */
+  locale?: string;
+}
+
+export const formatRelativeDate = (
+  value: Date | string,
+  { now = new Date(), locale }: FormatRelativeDateOptions = {},
+): string => {
+  const date = typeof value === "string" ? new Date(value) : value;
+  if (Number.isNaN(date.getTime())) return "unknown date";
+
+  const time = date.toLocaleTimeString(locale, {
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+  const days = calendarDaysAgo(date, now);
+
+  if (days === 0) return `today ${time}`;
+  if (days === 1) return `yesterday ${time}`;
+  if (days > 1 && days <= weekdayReach) {
+    const weekday = date.toLocaleDateString("en", { weekday: "long" });
+    return `last ${weekday} ${time}`;
+  }
+
+  const day = date.toLocaleDateString(locale, {
+    day: "numeric",
+    month: "short",
+    ...(date.getFullYear() === now.getFullYear() ? {} : { year: "numeric" }),
+  });
+  return `${day}, ${time}`;
+};