@ultimat3/cli 5.0.1 → 7.0.0

package/src/pr-threads.ts

@@ -0,0 +1,291 @@
+// The GraphQL a review lives behind, and the rows it becomes. `gh pr view --comments` shows ISSUE
+// comments; the findings a reviewer anchored to a line are `reviewThreads`, and the thread id that
+// resolves one exists in no REST response and in no web URL — this file is where that query stops
+// being folklore.
+
+import { t } from '@ultimat3/schema';
+import type { GhHost } from './gh';
+import { GhResponseInvalidError, ghGraphql } from './gh';
+import type { GhRepo } from './gh-target';
+
+/**
+ * How many threads one page holds. The query is built from it, so the report and the request can
+ * never disagree about what "the first page" was.
+ */
+export const THREAD_PAGE = 100;
+
+/** And how many comments of each. A long argument still shows the finding that opened it. */
+export const COMMENT_PAGE = 10;
+
+/**
+ * One document, because the two hazards are only visible together: a `reviewDecision` survives
+ * later pushes, so `CHANGES_REQUESTED` may predate the commits that addressed it, and the only
+ * thing that settles it is the head oid — asking for the threads and then asking for the head is
+ * two answers about two moments.
+ */
+export const REVIEW_QUERY =
+  'query($owner:String!,$name:String!,$n:Int!){repository(owner:$owner,name:$name){' +
+  'pullRequest(number:$n){number url headRefOid reviewDecision ' +
+  'commits(last:1){nodes{commit{oid committedDate}}} ' +
+  'latestOpinionatedReviews(first:20){nodes{state submittedAt author{login} commit{oid}}} ' +
+  `reviewThreads(first:${THREAD_PAGE}){pageInfo{hasNextPage} nodes{id isResolved isOutdated ` +
+  `path line originalLine comments(first:${COMMENT_PAGE}){totalCount ` +
+  'nodes{author{login} createdAt body}}}}}}}';
+
+const AUTHOR = t.nullable(t.object({ login: t.string }));
+
+const REVIEW_RESPONSE = t.object({
+  data: t.object({
+    repository: t.nullable(
+      t.object({
+        pullRequest: t.nullable(
+          t.object({
+            number: t.number,
+            url: t.string,
+            headRefOid: t.string,
+            reviewDecision: t.nullable(t.string),
+            commits: t.object({
+              nodes: t.array(
+                t.object({ commit: t.object({ oid: t.string, committedDate: t.string }) }),
+              ),
+            }),
+            latestOpinionatedReviews: t.object({
+              nodes: t.array(
+                t.object({
+                  state: t.string,
+                  submittedAt: t.nullable(t.string),
+                  author: AUTHOR,
+                  commit: t.nullable(t.object({ oid: t.string })),
+                }),
+              ),
+            }),
+            reviewThreads: t.object({
+              pageInfo: t.object({ hasNextPage: t.boolean }),
+              nodes: t.array(
+                t.object({
+                  id: t.string,
+                  isResolved: t.boolean,
+                  isOutdated: t.boolean,
+                  path: t.string,
+                  line: t.nullable(t.number),
+                  originalLine: t.nullable(t.number),
+                  comments: t.object({
+                    totalCount: t.number,
+                    nodes: t.array(
+                      t.object({ author: AUTHOR, createdAt: t.string, body: t.string }),
+                    ),
+                  }),
+                }),
+              ),
+            }),
+          }),
+        ),
+      }),
+    ),
+  }),
+});
+
+export interface PrComment {
+  readonly author: string;
+  readonly createdAt: string;
+  readonly body: string;
+}
+
+export interface PrThread {
+  readonly id: string;
+  readonly path: string;
+  /** The line the comment is anchored to NOW; `null` once the diff has moved under it. */
+  readonly line: number | null;
+  /** Where it was anchored when it was written — the only locator an outdated thread still has. */
+  readonly originalLine: number | null;
+  readonly isResolved: boolean;
+  readonly isOutdated: boolean;
+  readonly comments: readonly PrComment[];
+  /** Every comment on the thread, against the ten this page carries. */
+  readonly commentCount: number;
+}
+
+export interface PrReview {
+  readonly state: string;
+  readonly author: string;
+  readonly submittedAt: string | null;
+  readonly commit: string | null;
+  /**
+   * The review was submitted against a commit that is no longer the head. A verdict about the
+   * COMMIT, not about the clock: two reviews seconds apart can straddle a push, and a timestamp
+   * comparison would call one of them current.
+   */
+  readonly stale: boolean;
+}
+
+export interface PrReviewReport {
+  readonly repo: string;
+  readonly number: number;
+  readonly url: string;
+  readonly headSha: string;
+  readonly headCommittedAt: string | null;
+  readonly reviewDecision: string | null;
+  /** The review the decision came from, when one of the opinionated reviews states it. */
+  readonly decidingReview: PrReview | null;
+  readonly threads: readonly PrThread[];
+  /** More threads exist than one page holds, so `threads` is the first page and not the set. */
+  readonly truncated: boolean;
+}
+
+/** GitHub answers `null` for a deleted account. A row with no author still carries its finding. */
+const loginOf = (author: { readonly login: string } | null): string => author?.login ?? 'ghost';
+
+/**
+ * The review a `reviewDecision` came from. GitHub derives the decision from every opinionated
+ * review at once, so the one that STATES it is the one to date — falling back to the newest, which
+ * is the only defensible guess when none of them spells the decision out.
+ */
+export function decidingReview(
+  reviews: readonly PrReview[],
+  decision: string | null,
+): PrReview | null {
+  const stating = reviews.filter((review) => review.state === decision);
+  const pool = stating.length > 0 ? stating : reviews;
+  return pool.reduce<PrReview | null>(
+    (newest, review) =>
+      newest === null || (review.submittedAt ?? '') > (newest.submittedAt ?? '') ? review : newest,
+    null,
+  );
+}
+
+/** Unresolved first, then by file and line: the order an agent works the list in. */
+export function orderThreads(threads: readonly PrThread[]): readonly PrThread[] {
+  return [...threads].sort((left, right) => {
+    if (left.isResolved !== right.isResolved) return left.isResolved ? 1 : -1;
+    if (left.path !== right.path) return left.path < right.path ? -1 : 1;
+    return (left.line ?? left.originalLine ?? 0) - (right.line ?? right.originalLine ?? 0);
+  });
+}
+
+/**
+ * One round trip, one report. `repository` and `pullRequest` are both nullable in the schema
+ * because GraphQL answers `null` for either — but gh exits non-zero on the `errors` block that
+ * accompanies it, so reaching here with a `null` means GitHub answered a shape nobody has seen,
+ * and `X_GH_RESPONSE_INVALID` is a better sentence for that than a `TypeError` two frames later.
+ */
+export async function fetchReviewReport(
+  host: GhHost,
+  repo: GhRepo,
+  number: number,
+): Promise<PrReviewReport | null> {
+  const response = await ghGraphql(
+    host,
+    REVIEW_QUERY,
+    { owner: repo.owner, name: repo.name, n: number },
+    REVIEW_RESPONSE,
+    {
+      label: `gh api graphql (review threads on ${repo.slug}#${number})`,
+      fix: `gh pr view ${number} --repo ${repo.slug} --json number   # confirm the pull request is visible to this token`,
+    },
+  );
+  const pull = response.data.repository?.pullRequest;
+  if (pull === undefined || pull === null) return null;
+  const head = pull.commits.nodes[0]?.commit ?? null;
+  const reviews: readonly PrReview[] = pull.latestOpinionatedReviews.nodes.map((review) => ({
+    state: review.state,
+    author: loginOf(review.author),
+    submittedAt: review.submittedAt,
+    commit: review.commit?.oid ?? null,
+    stale: review.commit?.oid !== pull.headRefOid,
+  }));
+  return {
+    repo: repo.slug,
+    number: pull.number,
+    url: pull.url,
+    headSha: pull.headRefOid,
+    headCommittedAt: head?.committedDate ?? null,
+    reviewDecision: pull.reviewDecision,
+    decidingReview: decidingReview(reviews, pull.reviewDecision),
+    truncated: pull.reviewThreads.pageInfo.hasNextPage,
+    threads: orderThreads(
+      pull.reviewThreads.nodes.map((thread) => ({
+        id: thread.id,
+        path: thread.path,
+        line: thread.line,
+        originalLine: thread.originalLine,
+        isResolved: thread.isResolved,
+        isOutdated: thread.isOutdated,
+        commentCount: thread.comments.totalCount,
+        comments: thread.comments.nodes.map((comment) => ({
+          author: loginOf(comment.author),
+          createdAt: comment.createdAt,
+          body: comment.body,
+        })),
+      })),
+    ),
+  };
+}
+
+export const RESOLVE_MUTATION =
+  'mutation($t:ID!){resolveReviewThread(input:{threadId:$t}){thread{id isResolved}}}';
+
+// Both levels nullable, because both are nullable in GitHub's schema (`ResolveReviewThreadPayload.
+// thread` is an OBJECT, not a NON_NULL one) — and a payload that does not carry the thread it
+// claims to have resolved is exactly the answer this command must not read as a success.
+const RESOLVE_RESPONSE = t.object({
+  data: t.object({
+    resolveReviewThread: t.nullable(
+      t.object({ thread: t.nullable(t.object({ id: t.string, isResolved: t.boolean })) }),
+    ),
+  }),
+});
+
+/**
+ * Marks the CONVERSATION resolved, and says only that. Whether the finding is addressed is a fact
+ * about the code, which no GitHub mutation can observe — the summary this returns feeds a line
+ * that refuses to conflate the two.
+ */
+export async function resolveThread(host: GhHost, threadId: string): Promise<string> {
+  const fix = 'x pr review --json   # the id column is the thread id this mutation takes';
+  const label = `gh api graphql (resolve ${threadId})`;
+  const response = await ghGraphql(host, RESOLVE_MUTATION, { t: threadId }, RESOLVE_RESPONSE, {
+    label,
+    fix,
+  });
+  const thread = response.data.resolveReviewThread?.thread;
+  // A mutation that exited 0 and did not come back saying the thread is resolved has not told us
+  // it worked, and reporting `resolved` off the exit code alone is how a command claims an effect
+  // it never observed.
+  if (thread?.isResolved !== true) {
+    throw new GhResponseInvalidError({
+      label,
+      detail: 'the mutation returned no resolved thread',
+      fix,
+    });
+  }
+  // The id GitHub echoed, not the one that was sent: they are the same string on every success,
+  // and reporting the one we sent would make a summary that cannot tell a hit from a miss.
+  return thread.id;
+}
+
+export const REPLY_MUTATION =
+  'mutation($t:ID!,$b:String!){addPullRequestReviewThreadReply(' +
+  'input:{pullRequestReviewThreadId:$t,body:$b}){comment{id url}}}';
+
+const REPLY_RESPONSE = t.object({
+  data: t.object({
+    addPullRequestReviewThreadReply: t.nullable(
+      t.object({ comment: t.nullable(t.object({ id: t.string, url: t.string })) }),
+    ),
+  }),
+});
+
+/** A reply lands IN the thread, which is the only place a reviewer reads it. Returns its URL. */
+export async function replyToThread(host: GhHost, threadId: string, body: string): Promise<string> {
+  const fix = 'x pr review --json   # the id column is the thread id this mutation takes';
+  const label = `gh api graphql (reply on ${threadId})`;
+  const response = await ghGraphql(host, REPLY_MUTATION, { t: threadId, b: body }, REPLY_RESPONSE, {
+    label,
+    fix,
+  });
+  const url = response.data.addPullRequestReviewThreadReply?.comment?.url;
+  if (url === undefined || url === null) {
+    throw new GhResponseInvalidError({ label, detail: 'the mutation posted no comment', fix });
+  }
+  return url;
+}

package/src/prerender.ts

@@ -14,13 +14,19 @@ import { measureDocumentJs, writeBuildStats } from './budgets';
 import { routeDocument } from './dev-render';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands, writeIslands } from './island-bundle';
+import type { SkippedRoute } from './static-report';
+import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
 
 /**
- * `static` only. `isr` revalidates and `ssr`/`stream`/`spa` need a process, so writing any of them
- * to disk would publish a page whose staleness nothing can correct — and the route already
- * declared which of the five it is.
+ * `static` only. `isr` revalidates and `ssr`/`stream` need a process, so writing any of them to
+ * disk would publish a page whose staleness nothing can correct — and the route already declared
+ * which of the four it is.
+ *
+ * DERIVED from `skipReasonFor`, never a second `=== 'static'`: the answer and the reason reported
+ * beside it are one decision, and two copies of it is how a route came to be dropped silently.
  */
-export const isPrerenderable = (entry: RouteEntry): boolean => entry.config.render === 'static';
+export const isPrerenderable = (entry: RouteEntry): boolean =>
+  skipReasonFor({ surface: entry.surface, render: entry.config.render }) === null;
 
 export interface PrerenderOptions {
   readonly root: string;
@@ -30,6 +36,8 @@ export interface PrerenderOptions {
 }
 
 export interface PrerenderedPage {
+  /** The DECLARED route, `/blog/:slug` — one route can write many pages, and the report groups them. */
+  readonly route: string;
   readonly path: string;
   /** Relative to `out`, POSIX, as `renderStatic` computed it. */
   readonly file: string;
@@ -47,8 +55,13 @@ export interface PrerenderReport {
   readonly out: string;
   readonly buildId: string;
   readonly pages: readonly PrerenderedPage[];
-  /** Routes that exist and are not static. Reported, so "only 2 pages" is never a mystery. */
-  readonly skipped: readonly string[];
+  /**
+   * Every declared route that wrote no file, WITH the cause. A bare path list was the whole of
+   * #242: `.x/static/` held a partial site, the report said only which paths were missing, and a
+   * screenshot tool pointed at the directory filed "the island did not mount" against a route that
+   * had never been in the artifact. The reason is what tells an author whether an edit exists.
+   */
+  readonly skipped: readonly SkippedRoute[];
   /**
    * Routes whose budget this build could not weigh, with the reason. `X_BUDGET_UNMEASURED` is what
    * the gate then reports for each; this is the half that says WHY, which a per-route finding read
@@ -57,6 +70,8 @@ export interface PrerenderReport {
   readonly unmeasured: readonly UnmeasuredRoute[];
   /** Where the measured stats landed, for the `budgets` gate step to read. */
   readonly stats: string;
+  /** Where the emitted/skipped inventory landed, for `x build --target static` to read back. */
+  readonly report: string;
   /** Client entries emitted, one chunk each. Reported so "which JS shipped?" needs no unzip. */
   readonly islands: readonly string[];
 }
@@ -104,7 +119,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   const buildId = (await appManifest(options.root)).manifest.buildId;
   const origin = options.origin ?? DEFAULT_ORIGIN;
   const pages: PrerenderedPage[] = [];
-  const skipped: string[] = [];
+  const skipped: SkippedRoute[] = [];
   const routes: RouteStats[] = [];
   const unmeasured: UnmeasuredRoute[] = [];
 
@@ -115,8 +130,10 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   await writeIslands(islands, options.out);
 
   for (const entry of routeEntries()) {
-    if (!isPrerenderable(entry)) {
-      skipped.push(entry.path);
+    const facts = { surface: entry.surface, render: entry.config.render, route: entry.path };
+    const reason = skipReasonFor(facts);
+    if (reason !== null) {
+      skipped.push(skippedRoute(facts, reason));
       if (!declaresBudget(entry)) continue;
       // Non-fatal, and that is deliberate: an ssr page's `load` may want a request, a session or a
       // database this build does not have, and a `x build --target static` that started failing on
@@ -152,10 +169,24 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
         ),
       { buildId },
     );
+    // `enumeratePrerender` answers `[]` for a dynamic route with no `prerender()`, so a
+    // `render: 'static'` route with a param writes nothing and used to be reported NOWHERE — past
+    // the skip branch by its mode, absent from `pages` by its zero artifacts. A route in neither
+    // list is the defect this report exists to close, wearing its other shape.
+    if (artifacts.length === 0) {
+      skipped.push(skippedRoute(facts, 'no-prerender-paths'));
+      continue;
+    }
     for (const artifact of artifacts) {
       const file = join(options.out, artifact.outputPath);
       const bytes = await Bun.write(file, artifact.html);
-      pages.push({ path: artifact.path, file: artifact.outputPath, hash: artifact.hash, bytes });
+      pages.push({
+        route: entry.path,
+        path: artifact.path,
+        file: artifact.outputPath,
+        hash: artifact.hash,
+        bytes,
+      });
       // Measured from the document that was just written, so the `budgets` step compares a
       // declared budget against bytes that exist on disk rather than against a graph's estimate.
       const measured = await measureDocumentJs(artifact.html, options.out);
@@ -168,6 +199,16 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     }
   }
   const stats = await writeBuildStats(options.root, { routes });
+  // Written LAST and by the same call that writes the stats, so an app whose `prerender.ts` does
+  // not reach `prerenderSite` produces neither — and `x verify`'s `budgets` step already reds that
+  // app with `X_BUDGET_UNMEASURED`, which is why this side needs no second code of its own.
+  const report = await writeStaticReport(options.root, {
+    target: 'static',
+    out: options.out,
+    buildId,
+    emitted: pages.map((page) => ({ route: page.route, path: page.path, file: page.file })),
+    skipped,
+  });
   return {
     out: options.out,
     buildId,
@@ -175,6 +216,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     skipped,
     unmeasured,
     stats,
+    report,
     islands: islands.chunks.map((chunk) => chunk.file),
   };
 }

package/src/registry.ts

@@ -1,7 +1,9 @@
 // The command registry: the one list the parser, the help catalogue and the dispatcher all read.
 // A command that is not here does not exist — there is no second place to register one.
 
+import { affectedCommand } from './cmd-affected';
 import { buildCommand } from './cmd-build';
+import { ciCommand } from './cmd-ci';
 import { dbCommand } from './cmd-db';
 import { deployCommand } from './cmd-deploy';
 import { devCommand } from './cmd-dev';
@@ -19,9 +21,11 @@ import { mcpCommand } from './cmd-mcp';
 import { newCommand } from './cmd-new';
 import { plannedCommands } from './cmd-planned';
 import { policyCommand } from './cmd-policy';
+import { prCommand } from './cmd-pr';
 import { actionsCommand, entitiesCommand, queriesCommand } from './cmd-registries';
 import { routesCommand } from './cmd-routes';
 import { secretsCommand } from './cmd-secrets';
+import { shotCommand } from './cmd-shot';
 import { tasksCommand } from './cmd-tasks';
 import { testCommand } from './cmd-test';
 import { verifyCommand } from './cmd-verify';
@@ -69,6 +73,10 @@ const CORE: readonly CliCommand[] = [
   errorsCommand,
   docsCommand,
   fixCommand,
+  affectedCommand,
+  shotCommand,
+  prCommand,
+  ciCommand,
 ];
 
 /**