@clearlydev/nx-archweave 0.2.1 → 0.3.0

package/README.md

@@ -2,10 +2,11 @@
 
 Nx generators that get a workspace ready to work on with one preset:
 
-- FSD Lite structure with enforced module boundaries
+- an FSD Lite lint rule for the frontend app's layers (`warn` or `error` by preset), plus slice generators
+- frontend/backend boundaries as lint errors between the projects it tags, when there is a backend
 - AI agent rules
 - GitHub templates
-- optional AI PR review (Claude, Gemini, GPT, Cursor)
+- optional AI PR review with the provider you choose (Claude supported; Gemini, GPT and Cursor in beta)
 
 Starting a brand-new workspace instead? Use [`create-nx-archweave`](https://www.npmjs.com/package/create-nx-archweave). It creates the workspace, installs this plugin, and runs `init`, all in one command.
 
@@ -32,7 +33,7 @@ bun nx g @clearlydev/nx-archweave:doctor           # bun
 - **Requirements:** Node >= 22.18, plus one of npm, pnpm >= 10, yarn (classic or berry) or bun. All four package managers are first-class.
 - Generators detect the workspace's real package manager from its lockfiles.
 - The examples below use `pnpm nx g`. With another package manager, run the same generator the way the `doctor` commands above show.
-- The package ships as a self-contained bundle. Its only runtime dependency is `@nx/devkit`.
+- The package ships its own code as a bundle. Its runtime dependencies are `@nx/devkit` and `jsonc-parser`, which nx already depends on at the same version.
 
 ## Quick start
 
@@ -213,9 +214,11 @@ Review is fully optional and isn't tied to one provider.
 | `--provider` | Workflow file | Required secret |
 | --- | --- | --- |
 | `claude` (default) | `.github/workflows/claude-code-review.yml` | `CLAUDE_CODE_OAUTH_TOKEN` |
-| `gemini` | `.github/workflows/gemini-code-review.yml` | `GEMINI_API_KEY` |
-| `gpt` | `.github/workflows/gpt-code-review.yml` | `OPENAI_API_KEY` |
-| `cursor` | `.github/workflows/cursor-code-review.yml` | `CURSOR_API_KEY` |
+| `gemini` (beta) | `.github/workflows/gemini-code-review.yml` | `GEMINI_API_KEY` |
+| `gpt` (beta) | `.github/workflows/gpt-code-review.yml` | `OPENAI_API_KEY` |
+| `cursor` (beta) | `.github/workflows/cursor-code-review.yml` | `CURSOR_API_KEY` |
+
+What each provider has been checked on, where to get its secret, and known issues: [Provider status](https://github.com/clearlydev/nx-archweave/blob/main/docs/pr-review.md#provider-status).
 
 Modes:
 

package/dist/bin/review-verdict.js

@@ -2,7 +2,8 @@
 
 // src/bin/review-verdict.ts
 import { spawnSync } from "node:child_process";
-import { realpathSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { appendFileSync, realpathSync } from "node:fs";
 
 // ../review-policy/dist/schema/review-finding.js
 function computeVerdict(findings) {
@@ -149,15 +150,29 @@ var NO_ROUND_NOTICE = {
   en: "\u26A0\uFE0F This run of the review posted no summary comment for the current commit, so there is no verdict for it (an earlier round is never reused). The verdict gate stays green; please review this PR manually.",
   ko: "\u26A0\uFE0F \uC774\uBC88 \uB9AC\uBDF0 \uC2E4\uD589\uC774 \uD604\uC7AC \uCEE4\uBC0B\uC5D0 \uB300\uD55C \uC694\uC57D \uCF54\uBA58\uD2B8\uB97C \uAC8C\uC2DC\uD558\uC9C0 \uC54A\uC544 verdict\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4(\uC774\uC804 \uB77C\uC6B4\uB4DC\uB294 \uC7AC\uC0AC\uC6A9\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4). verdict \uAC8C\uC774\uD2B8\uB294 \uB179\uC0C9\uC73C\uB85C \uB450\uB2C8 \uC774 PR\uC740 \uC0AC\uB78C\uC774 \uC9C1\uC811 \uB9AC\uBDF0\uD574 \uC8FC\uC138\uC694."
 };
+var NO_SUMMARY_NOTICE = {
+  en: "\u26D4 AI review posted no summary for this commit, so there is no verdict for it and the review check fails. Review this PR manually, or re-run all jobs to review it again.",
+  ko: "\u26D4 AI \uB9AC\uBDF0\uAC00 \uC774 \uCEE4\uBC0B\uC5D0 \uB300\uD55C \uC694\uC57D\uC744 \uAC8C\uC2DC\uD558\uC9C0 \uC54A\uC544 verdict\uAC00 \uC5C6\uACE0, review \uCCB4\uD06C\uB294 \uC2E4\uD328\uD569\uB2C8\uB2E4. \uC774 PR\uC744 \uC9C1\uC811 \uB9AC\uBDF0\uD558\uAC70\uB098, \uBAA8\uB4E0 \uC7A1\uC744 \uB2E4\uC2DC \uC2E4\uD589\uD574 \uB2E4\uC2DC \uB9AC\uBDF0\uBC1B\uC73C\uC138\uC694."
+};
+var UNREADABLE_SUMMARY_NOTICE = {
+  en: "\u26D4 AI review posted a summary whose findings block could not be machine-read (missing or invalid), so there is no verdict for this commit and the review check fails. Review this PR manually, or re-run all jobs to review it again.",
+  ko: "\u26D4 AI \uB9AC\uBDF0 \uC694\uC57D\uC758 findings \uBE14\uB85D\uC744 \uAE30\uACC4 \uD310\uB3C5\uD558\uC9C0 \uBABB\uD574(\uB204\uB77D \uB610\uB294 \uC190\uC0C1) \uC774 \uCEE4\uBC0B\uC758 verdict\uAC00 \uC5C6\uACE0, review \uCCB4\uD06C\uB294 \uC2E4\uD328\uD569\uB2C8\uB2E4. \uC774 PR\uC744 \uC9C1\uC811 \uB9AC\uBDF0\uD558\uAC70\uB098, \uBAA8\uB4E0 \uC7A1\uC744 \uB2E4\uC2DC \uC2E4\uD589\uD574 \uB2E4\uC2DC \uB9AC\uBDF0\uBC1B\uC73C\uC138\uC694."
+};
+function renderCommitLine(locale, shortSha) {
+  return locale === "en" ? `<sub>Commit \`${shortSha}\` \xB7 this comment is updated on every review round.</sub>` : `<sub>\uCEE4\uBC0B \`${shortSha}\` \xB7 \uC774 \uCF54\uBA58\uD2B8\uB294 \uB9AC\uBDF0 \uB77C\uC6B4\uB4DC\uB9C8\uB2E4 \uAC31\uC2E0\uB429\uB2C8\uB2E4.</sub>`;
+}
 var HEAD_LINE = {
-  en: (sha) => `<sub>Commit \`${sha.slice(0, 7)}\` \xB7 this comment is updated on every review round.</sub>`,
-  ko: (sha) => `<sub>\uCEE4\uBC0B \`${sha.slice(0, 7)}\` \xB7 \uC774 \uCF54\uBA58\uD2B8\uB294 \uB9AC\uBDF0 \uB77C\uC6B4\uB4DC\uB9C8\uB2E4 \uAC31\uC2E0\uB429\uB2C8\uB2E4.</sub>`
+  en: (sha) => renderCommitLine("en", sha.slice(0, 7)),
+  ko: (sha) => renderCommitLine("ko", sha.slice(0, 7))
 };
 function withHead(lines, locale, headSha) {
   return (headSha === void 0 ? lines : [...lines, "", HEAD_LINE[locale](headSha)]).join("\n");
 }
-function renderUnparseableNotice(locale, headSha) {
-  return withHead([VERDICT_MARKER, UNPARSEABLE_NOTICE[locale]], locale, headSha);
+function renderUnparseableNotice(locale, headSha, failClosed = false) {
+  return withHead([VERDICT_MARKER, (failClosed ? UNREADABLE_SUMMARY_NOTICE : UNPARSEABLE_NOTICE)[locale]], locale, headSha);
+}
+function renderNoSummaryNotice(locale, headSha) {
+  return withHead([VERDICT_MARKER, NO_SUMMARY_NOTICE[locale]], locale, headSha);
 }
 function renderNoRoundNotice(locale, headSha) {
   return withHead([VERDICT_MARKER, NO_ROUND_NOTICE[locale]], locale, headSha);
@@ -205,14 +220,16 @@ function computeRoundHistory(rounds) {
 }
 function runVerdictGate(input) {
   const rounds = collectRounds(input.comments);
-  if (rounds.length === 0)
-    return { kind: "no-review" };
+  const reviewRan = input.reviewRan === true;
+  if (rounds.length === 0) {
+    return reviewRan ? { kind: "no-summary", commentBody: renderNoSummaryNotice(input.locale, input.headSha) } : { kind: "no-review" };
+  }
   const latest = rounds[rounds.length - 1];
   if (input.roundAfterId !== void 0 && (latest.id === void 0 || latest.id <= input.roundAfterId)) {
-    return { kind: "no-round", commentBody: renderNoRoundNotice(input.locale, input.headSha) };
+    return reviewRan ? { kind: "no-summary", commentBody: renderNoSummaryNotice(input.locale, input.headSha) } : { kind: "no-round", commentBody: renderNoRoundNotice(input.locale, input.headSha) };
   }
   if (latest.extraction.status !== "ok") {
-    return { kind: "unparseable", commentBody: renderUnparseableNotice(input.locale, input.headSha) };
+    return { kind: "unparseable", commentBody: renderUnparseableNotice(input.locale, input.headSha, reviewRan), failClosed: reviewRan };
   }
   const verdict = computeVerdict(latest.extraction.findings);
   const commentBody = renderVerdictComment({
@@ -231,7 +248,19 @@ var realExec = (command, args, stdin) => {
   const result = spawnSync(command, args, { encoding: "utf-8", input: stdin });
   return { status: result.status ?? null, stdout: result.stdout ?? "" };
 };
-function runReviewVerdictBin(env, exec) {
+var realWriteOutput = (path, text) => appendFileSync(path, text);
+function outputModePath(env) {
+  return env["ARCHWEAVE_VERDICT_OUTPUT"] === "github-output" && env["GITHUB_OUTPUT"] ? env["GITHUB_OUTPUT"] : void 0;
+}
+function renderStepOutputs(commentBody, previousId, blocked) {
+  let delimiter;
+  do
+    delimiter = `ARCHWEAVE_${randomBytes(8).toString("hex")}`;
+  while (commentBody.split("\n").includes(delimiter));
+  return [`comment-body<<${delimiter}`, commentBody, delimiter, `previous-comment-id=${previousId ?? ""}`, `blocked=${blocked}`, ""].join("\n");
+}
+var UNREAD_COMMENTS_ERROR = "::error title=Review verdict not computed::Could not read PR comments, so the verdict could not be computed. Re-run the failed jobs to retry. If it fails again, check that the review job has pull-requests: read.";
+function runReviewVerdictBin(env, exec, writeOutput = realWriteOutput) {
   const logs = [];
   const repo = env["GITHUB_REPOSITORY"];
   const pr = env["ARCHWEAVE_PR_NUMBER"];
@@ -245,41 +274,54 @@ function runReviewVerdictBin(env, exec) {
   const roundAfterId = watermark !== void 0 && /^\d+$/.test(watermark) ? Number(watermark) : void 0;
   const sha = env["ARCHWEAVE_HEAD_SHA"];
   const headSha = sha !== void 0 && /^[0-9a-f]{7,40}$/i.test(sha) ? sha : void 0;
+  const outputPath = outputModePath(env);
   const fetched = exec("gh", ["api", `repos/${repo}/issues/${pr}/comments`, "--paginate"]);
-  if (fetched.status !== 0) {
-    logs.push("verdict gate: could not fetch PR comments via gh \u2014 skipping (check stays green).");
-    return { exitCode: 0, logs };
-  }
-  const pages = splitConcatenatedJson(fetched.stdout);
+  const pages = fetched.status === 0 ? splitConcatenatedJson(fetched.stdout) : null;
   if (pages === null) {
-    logs.push("verdict gate: unexpected gh output \u2014 skipping (check stays green).");
+    if (outputPath !== void 0) return { exitCode: 1, logs: [UNREAD_COMMENTS_ERROR] };
+    logs.push(
+      fetched.status !== 0 ? "verdict gate: could not fetch PR comments via gh \u2014 skipping (check stays green)." : "verdict gate: unexpected gh output \u2014 skipping (check stays green)."
+    );
     return { exitCode: 0, logs };
   }
   const comments = pages.flatMap((page) => Array.isArray(page) ? page : []).filter(
     (c) => c !== null && typeof c === "object" && typeof c.body === "string" && c.user?.type === "Bot"
   ).map((c) => ({ body: c.body, id: typeof c.id === "number" ? c.id : void 0 }));
-  const result = runVerdictGate({ comments, maxRounds, locale, roundAfterId, headSha });
+  const reviewRan = outputPath !== void 0 && roundAfterId !== void 0;
+  const result = runVerdictGate({ comments, maxRounds, locale, roundAfterId, headSha, reviewRan });
   if (result.kind === "no-review") {
     logs.push("verdict gate: no review rounds found on this PR \u2014 nothing to judge.");
     return { exitCode: 0, logs };
   }
   const previous = [...comments].reverse().find((c) => c.body.includes(VERDICT_MARKER) && c.id !== void 0);
-  const payload = JSON.stringify({ body: result.commentBody });
-  const updated = previous !== void 0 && exec("gh", ["api", "-X", "PATCH", `repos/${repo}/issues/comments/${previous.id}`, "--input", "-"], payload).status === 0;
-  if (!updated) {
-    const post = exec("gh", ["api", "-X", "POST", `repos/${repo}/issues/${pr}/comments`, "--input", "-"], payload);
-    if (post.status !== 0) logs.push("verdict gate: could not post the verdict comment (continuing).");
+  const failedReview = result.kind === "no-summary" || result.kind === "unparseable" && result.failClosed;
+  const settled = !failedReview && (result.kind === "no-round" || result.kind === "unparseable");
+  const blocked = failedReview || result.kind === "verdict" && result.exitCode !== 0;
+  if (outputPath !== void 0) {
+    writeOutput(outputPath, renderStepOutputs(result.commentBody, previous?.id, blocked));
+  } else {
+    const payload = JSON.stringify({ body: result.commentBody });
+    const updated = previous !== void 0 && exec("gh", ["api", "-X", "PATCH", `repos/${repo}/issues/comments/${previous.id}`, "--input", "-"], payload).status === 0;
+    if (!updated) {
+      const post = exec("gh", ["api", "-X", "POST", `repos/${repo}/issues/${pr}/comments`, "--input", "-"], payload);
+      if (post.status !== 0) logs.push("verdict gate: could not post the verdict comment (continuing).");
+    }
   }
-  if (result.kind === "no-round") {
-    logs.push("verdict gate: this run posted no review round for the current commit \u2014 earlier rounds are not judged again; check stays green.");
+  if (failedReview) {
+    logs.push(
+      result.kind === "no-summary" ? "::error title=AI review posted no summary::The AI review ran but posted no summary for this commit, so there is no verdict. Review the PR manually, or re-run all jobs." : "::error title=AI review summary unreadable::The AI review summary has no readable findings block, so there is no verdict. Review the PR manually, or re-run all jobs."
+    );
     return { exitCode: 0, logs };
   }
-  if (result.kind === "unparseable") {
-    logs.push("verdict gate: review output was not machine-readable \u2014 human review requested, check stays green.");
+  if (settled) {
+    logs.push(
+      result.kind === "no-round" ? "verdict gate: this run posted no review round for the current commit \u2014 earlier rounds are not judged again; check stays green." : "verdict gate: review output was not machine-readable \u2014 human review requested, check stays green."
+    );
     return { exitCode: 0, logs };
   }
+  if (result.kind !== "verdict") return { exitCode: 0, logs };
   logs.push(`verdict gate: ${result.verdict}`);
-  return { exitCode: result.exitCode, logs };
+  return { exitCode: outputPath === void 0 ? result.exitCode : 0, logs };
 }
 function splitConcatenatedJson(stdout) {
   const text = stdout.trim();