crysk 0.3.3 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/dist/SKILL-dsnffnfp.md +140 -0
  2. package/dist/SKILL-gnrbph72.md +140 -0
  3. package/dist/SKILL-kq0xejn3.md +553 -0
  4. package/dist/SKILL-qaqsbygw.md +66 -0
  5. package/dist/SKILL-vws0aqb8.md +553 -0
  6. package/dist/ci-admission-t0f5qwth.md +128 -0
  7. package/dist/cli.js +408 -155
  8. package/dist/index.js +151 -20
  9. package/package.json +2 -2
  10. package/skills/crysk-ci-setup/SKILL.md +1 -1
  11. package/skills/crysk-ci-setup/references/ci-admission.md +1 -1
  12. package/skills/crysk-loop/SKILL.md +19 -8
  13. package/skills/crysk-pr/SKILL.md +1 -1
  14. package/src/assets.ts +2 -2
  15. package/src/ci/gates.ts +9 -6
  16. package/src/ci/platform-config.ts +127 -0
  17. package/src/ci/platform-report.ts +702 -0
  18. package/src/ci/platform.ts +449 -0
  19. package/src/ci/reporter.ts +9 -7
  20. package/src/ci/review-admission.ts +8 -4
  21. package/src/ci/setup.ts +112 -9
  22. package/src/compare/loop.ts +9 -1
  23. package/src/compare/martian-adapter.ts +1 -1
  24. package/src/index.ts +1 -1
  25. package/src/pr/admission.ts +53 -11
  26. package/src/pr/ci-admission-gate.ts +2 -1
  27. package/src/pr/finding-state-record.ts +58 -0
  28. package/src/pr/gate-record.ts +22 -0
  29. package/src/pr/inline.ts +3 -0
  30. package/src/pr/posting.ts +4 -0
  31. package/src/pr/pr-status.ts +27 -7
  32. package/src/pr/pr.ts +39 -8
  33. package/src/pr/preflight.ts +43 -1
  34. package/src/pr/publish-outcome.ts +10 -2
  35. package/src/pr/review-pr.ts +5 -3
  36. package/src/rereview/classify.ts +4 -0
  37. package/src/rereview/prepare.ts +47 -22
  38. package/src/rereview/state.ts +34 -8
  39. package/src/review/report.ts +34 -14
  40. package/src/security/published-text.ts +161 -0
  41. package/src/triage/triage.ts +2 -1
  42. package/src/updater.ts +1 -1
package/src/ci/setup.ts CHANGED
@@ -38,6 +38,13 @@ import {
38
38
  } from "node:fs/promises";
39
39
  import path from "node:path";
40
40
  import type { ErrorClass, SetupRecord } from "#ci/outcome";
41
+ import { appendGithubOutput } from "#ci/platform";
42
+ import {
43
+ assertPlatformPerson,
44
+ deliverPlatformRepoLayer,
45
+ PlatformConfigError,
46
+ readPlatformConfig,
47
+ } from "#ci/platform-config";
41
48
  import type { ConfigPlan } from "#ci/review-levels";
42
49
  import {
43
50
  OVERRIDE_COMMAND,
@@ -45,6 +52,7 @@ import {
45
52
  REVIEW_COMMAND,
46
53
  recordTempPath,
47
54
  } from "#ci/trigger";
55
+ import { resolveRepoRoot } from "#git/git";
48
56
  import { parseLocalConfig, parseRoutingConfig } from "#review/preflight";
49
57
  import { commandForms } from "../brand";
50
58
  import {
@@ -649,6 +657,13 @@ export interface MaterializeCiOpenCodeDataOptions {
649
657
  opencodeAuth?: string;
650
658
  home?: string;
651
659
  env?: Readonly<Record<string, string | undefined>>;
660
+ // Platform mode: the person layer the Crysk platform returned (`{}` when it
661
+ // sent none). Written into the same personal file as `routing`; its own
662
+ // `routing` wins over the input. Present means platform mode, in which the
663
+ // personal file belongs to this run: a file an earlier run left behind is
664
+ // removed when nothing is to be written, so it can never be read as this run's
665
+ // person layer on a runner whose HOME outlives the job.
666
+ platformPerson?: Record<string, unknown>;
652
667
  }
653
668
 
654
669
  // The file the publisher reads when this step fails on a malformed input, and
@@ -688,6 +703,8 @@ function messageOf(error: unknown): string {
688
703
  // directory — empty/unset fails loud with no cwd fallback, because falling
689
704
  // back would write routing into the checkout (.prhero/config.json), which
690
705
  // the repo parser rejects. Never log the auth blob; never inject readerFn.
706
+ // In platform mode the platform's person layer joins the routing in that one
707
+ // file; `routing` is the platform's when it sent one, else the input's, as today.
691
708
  export async function materializeCiOpenCodeData(
692
709
  options: MaterializeCiOpenCodeDataOptions = {},
693
710
  ): Promise<void> {
@@ -701,9 +718,14 @@ export async function materializeCiOpenCodeData(
701
718
 
702
719
  const routingRaw = options.routing ?? env.ROUTING_INPUT ?? "";
703
720
  const authRaw = options.opencodeAuth ?? env.OPENCODE_AUTH_INPUT ?? "";
721
+ const platformMode = options.platformPerson !== undefined;
722
+ const platformPerson = options.platformPerson ?? {};
723
+ // The input is parsed only when it is the one that will be written: a
724
+ // routing the platform overrides is not this run's configuration.
725
+ const platformRouting = platformPerson.routing !== undefined;
704
726
 
705
727
  let routingConfig: ReturnType<typeof parseRoutingConfig> | null = null;
706
- if (routingRaw.trim() !== "") {
728
+ if (routingRaw.trim() !== "" && !platformRouting) {
707
729
  let parsed: unknown;
708
730
  try {
709
731
  parsed = JSON.parse(routingRaw);
@@ -760,13 +782,20 @@ export async function materializeCiOpenCodeData(
760
782
  authBody = authRaw;
761
783
  }
762
784
 
763
- if (routingConfig !== null) {
764
- const layout = prheroLayout(home);
765
- await mkdir(layout.dir, { recursive: true });
766
- await writeFile(
767
- layout.reviewConfigPath,
768
- `${JSON.stringify({ routing: routingConfig }, null, 2)}\n`,
769
- );
785
+ const personFile = prheroLayout(home).reviewConfigPath;
786
+ // Validated whole by the engine's person parser before anything is written.
787
+ if (Object.keys(platformPerson).length > 0) {
788
+ assertPlatformPerson(platformPerson, personFile);
789
+ }
790
+ const personBody: Record<string, unknown> = {
791
+ ...platformPerson,
792
+ ...(routingConfig === null ? {} : { routing: routingConfig }),
793
+ };
794
+ if (Object.keys(personBody).length > 0) {
795
+ await mkdir(path.dirname(personFile), { recursive: true });
796
+ await writeFile(personFile, `${JSON.stringify(personBody, null, 2)}\n`);
797
+ } else if (platformMode) {
798
+ await rm(personFile, { force: true });
770
799
  }
771
800
 
772
801
  if (authBody !== undefined) {
@@ -780,6 +809,48 @@ export async function materializeCiOpenCodeData(
780
809
  interface CiOpenCodeSetupDeps {
781
810
  env: Readonly<Record<string, string | undefined>>;
782
811
  stderr: (text: string) => void;
812
+ // Where the checkout is (the engine resolves its operator root from here).
813
+ cwd: string;
814
+ appendOutput: (text: string) => void;
815
+ }
816
+
817
+ // Workflow-command data escaping, as the runner's own toolkit does it.
818
+ function escapeCommandData(text: string): string {
819
+ return text.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
820
+ }
821
+
822
+ // Platform mode only (the connect step announced a config file): the repo layer
823
+ // the platform sent reaches the run step as the `repo-config` output, which it
824
+ // passes as `--config`, but ONLY when the checkout has no repo config of its own.
825
+ // Returns whether the layer it delivered sets `post`.
826
+ async function deliverPlatformRepo(
827
+ deps: CiOpenCodeSetupDeps,
828
+ platformFile: string,
829
+ repo: Record<string, unknown>,
830
+ ): Promise<boolean> {
831
+ if (Object.keys(repo).length === 0) return false;
832
+ let root: string;
833
+ try {
834
+ root = await resolveRepoRoot(deps.cwd);
835
+ } catch (error) {
836
+ throw new PlatformConfigError(
837
+ `the checked-out repository could not be found to decide whether it has its own config: ${messageOf(error)}`,
838
+ );
839
+ }
840
+ const result = await deliverPlatformRepoLayer({
841
+ repo,
842
+ root,
843
+ dir: path.dirname(platformFile),
844
+ });
845
+ if (result.status === "repo-file-wins") {
846
+ deps.stderr(
847
+ `::notice::${escapeCommandData(`Crysk platform config: this repository has its own ${path.relative(root, result.file)}, so it is used as is and the platform's repository settings are ignored.`)}\n`,
848
+ );
849
+ } else if (result.status === "written") {
850
+ deps.appendOutput(`repo-config=${result.file}\n`);
851
+ return repo.post !== undefined;
852
+ }
853
+ return false;
783
854
  }
784
855
 
785
856
  // WHY tmp then rename, the same as the trigger's record: the publisher reads the
@@ -807,12 +878,41 @@ async function writeSetupRecord(
807
878
  // any other failure (HOME, a write) stays unclassified, with no record.
808
879
  async function runCiOpenCodeSetup(deps: CiOpenCodeSetupDeps): Promise<number> {
809
880
  try {
810
- await materializeCiOpenCodeData({ env: deps.env });
881
+ const platformFile = deps.env.CRYSK_PLATFORM_CONFIG_FILE ?? "";
882
+ const platform =
883
+ platformFile === "" ? undefined : readPlatformConfig(platformFile);
884
+ // The connect step announces a config file only when the platform sent
885
+ // configuration, so a connected run with none is told apart by this
886
+ // presence boolean: it still owns the personal file (see the option).
887
+ const platformMode =
888
+ platform !== undefined || deps.env.CRYSK_PLATFORM_CONNECTED === "true";
889
+ await materializeCiOpenCodeData({
890
+ env: deps.env,
891
+ ...(platformMode ? { platformPerson: platform?.person ?? {} } : {}),
892
+ });
893
+ // WHY the run step needs to know: it passes `--post` whenever the `post`
894
+ // input is true (the default), and an explicit CLI option outranks the
895
+ // config, so a `post` the platform set would never take effect.
896
+ let postFromPlatform = platform?.person.post !== undefined;
897
+ if (platform !== undefined) {
898
+ const repoPost = await deliverPlatformRepo(
899
+ deps,
900
+ platformFile,
901
+ platform.repo,
902
+ );
903
+ postFromPlatform ||= repoPost;
904
+ }
905
+ if (postFromPlatform) deps.appendOutput("post-from-platform=true\n");
811
906
  return 0;
812
907
  } catch (error) {
813
908
  deps.stderr(
814
909
  `crysk: failed to materialize OpenCode CI data: ${messageOf(error)}\n`,
815
910
  );
911
+ if (error instanceof PlatformConfigError) {
912
+ deps.stderr(
913
+ `::error::${escapeCommandData(`Crysk platform mode failed: ${messageOf(error)}`)}\n`,
914
+ );
915
+ }
816
916
  const outcomeDir = deps.env.CRYSK_OUTCOME_DIR ?? "";
817
917
  if (error instanceof SetupInputError && outcomeDir !== "") {
818
918
  try {
@@ -838,6 +938,9 @@ if (import.meta.main) {
838
938
  stderr: (text) => {
839
939
  process.stderr.write(text);
840
940
  },
941
+ cwd: process.cwd(),
942
+ appendOutput: (text) =>
943
+ appendGithubOutput(process.env.GITHUB_OUTPUT, text),
841
944
  }),
842
945
  );
843
946
  }
@@ -7,6 +7,8 @@
7
7
  // "carried from <sha>" is a prior verdict copied to a new head (not a review),
8
8
  // "overridden" and "stopped by a maintainer" are a human ending the loop.
9
9
 
10
+ import { isManualReviewHold } from "#pr/preflight";
11
+
10
12
  export interface RawStatus {
11
13
  createdAt: string;
12
14
  context: string;
@@ -40,6 +42,7 @@ type GateEvent =
40
42
  | "unverified-fixes"
41
43
  | "budget-carried"
42
44
  | "error"
45
+ | "held"
43
46
  | "pending"
44
47
  | "other-success"
45
48
  | "other-failure";
@@ -55,7 +58,11 @@ export function classifyStatus(status: RawStatus): GateEvent {
55
58
  const d = status.description ?? "";
56
59
  switch (status.state) {
57
60
  case "pending":
58
- return "pending";
61
+ // Since Stage 2 #12 a capped rule (budget used up, manual_only) holds the head pending until a
62
+ // human acts. No run holds it, so it is not a review in flight: it is a head that is not green.
63
+ return isManualReviewHold({ state: status.state, description: d })
64
+ ? "held"
65
+ : "pending";
59
66
  case "error":
60
67
  return "error";
61
68
  case "success":
@@ -145,6 +152,7 @@ const NOT_GREEN = new Set<GateEvent>([
145
152
  "budget-exhausted",
146
153
  "size-skipped",
147
154
  "error",
155
+ "held",
148
156
  "other-failure",
149
157
  ]);
150
158
 
@@ -1,6 +1,6 @@
1
1
  // Project a pr-hero findings.json onto Martian's offline candidate shape.
2
2
  // Pure: no I/O, no judge, no precision/recall. The judge is theirs; this
3
- // only makes our artifacts injectable. See docs/martian-bench.md.
3
+ // only makes our artifacts injectable. See benchmarks/martian/README.md.
4
4
 
5
5
  import type { Finding } from "#review/findings";
6
6
 
package/src/index.ts CHANGED
@@ -2,7 +2,7 @@
2
2
  // Public API surface; the deep-review lab consumes exactly these exports.
3
3
 
4
4
  export const ENGINE_NAME = "pr-hero";
5
- export const ENGINE_VERSION = "0.3.3";
5
+ export const ENGINE_VERSION = "0.4.0";
6
6
 
7
7
  // errors and git/refs used to reach this surface only through re-exports in
8
8
  // review/preflight.ts; they are exported directly now that those re-exports
@@ -38,6 +38,8 @@ import {
38
38
  type CommitStatusFact,
39
39
  clipStatusDescription,
40
40
  commitStatusRequest,
41
+ heldVerdictSha,
42
+ manualReviewHoldDescription,
41
43
  partialReviewAgainDescription,
42
44
  partialReviewDescription,
43
45
  prHtmlUrl,
@@ -318,7 +320,7 @@ export interface AdmissionStatusInput {
318
320
  }
319
321
 
320
322
  export interface AdmissionStatusDecision {
321
- state: "success" | "failure";
323
+ state: "success" | "failure" | "pending";
322
324
  description: string;
323
325
  }
324
326
 
@@ -335,13 +337,21 @@ type CarriedReason = Exclude<AdmissionStatusReason, "same-head">;
335
337
 
336
338
  // Every rule that skips a review carries the last verdict the same way (budget-exhausted-carry S2): the
337
339
  // rule is respected, so no review runs, and the head reads what the last review decided. Same-head is the
338
- // one exception: that head's own status already exists.
340
+ // one exception: that head's own status already exists. A capped rule holds a green (holdsForManualReview).
339
341
  function isCarriedReason(
340
342
  reason: AdmissionStatusReason,
341
343
  ): reason is CarriedReason {
342
344
  return reason !== "same-head";
343
345
  }
344
346
 
347
+ // ROADMAP Stage 2 #12: the rules that cap automatic reviews. Under them no later push is reviewed on its
348
+ // own, so carrying a green would let code no review read merge (measured: one PR merged green over 11
349
+ // unreviewed commits).
350
+ // The head waits for a manual review instead; a red still carries, since it already blocks.
351
+ function holdsForManualReview(reason: CarriedReason): boolean {
352
+ return reason === "max-attempts-exhausted" || reason === "manual-only-policy";
353
+ }
354
+
345
355
  // The readers below rewrite a legacy `pr-hero` lead into `crysk` first (canonicalStatusText), so the
346
356
  // patterns and the builders speak one spelling.
347
357
  const BLOCKING_COUNT = /^crysk: (\d+) blocking finding\(s\)/;
@@ -601,6 +611,12 @@ export function admissionSkipDecision(
601
611
  const verdict = newestCarriedVerdict(input.carried.statuses);
602
612
  if (verdict === undefined) return failClosed(label);
603
613
  if (verdict.state === "success") {
614
+ if (holdsForManualReview(input.reason)) {
615
+ return {
616
+ state: "pending",
617
+ description: manualReviewHoldDescription(label, input.carried.sha),
618
+ };
619
+ }
604
620
  // A carried unverified green stays unverified: chaining it never turns it into a green a review earned.
605
621
  const answeredCount = answeredCountIn(verdict.description ?? "");
606
622
  return {
@@ -638,6 +654,12 @@ export function admissionSkipDecision(
638
654
  answered.blocking > 0 &&
639
655
  answered.blocking >= blocking
640
656
  ) {
657
+ if (holdsForManualReview(input.reason)) {
658
+ return {
659
+ state: "pending",
660
+ description: manualReviewHoldDescription(label, input.carried.sha),
661
+ };
662
+ }
641
663
  return {
642
664
  state: "success",
643
665
  description: unverifiedFixesDescription(
@@ -676,6 +698,10 @@ const CARRY_WALK_CAP = 20;
676
698
  // missing from the list fails closed.
677
699
  // WHY a failed read ends the walk: a commit whose statuses did not read is not a commit with no verdict,
678
700
  // so skipping it would carry an older verdict across a read that never happened.
701
+ // WHY a hold redirects the walk (Stage 2 #12): a hold is no verdict, but it names the commit whose verdict
702
+ // it held. Under a used-up budget every push is held, so without the jump a PR with more commits since its
703
+ // last review than the cap would fail closed red although that review is still on the PR. The jump only
704
+ // ever moves to an older commit, so the walk ends, and the cap restarts from the commit it lands on.
679
705
  async function findCarriedVerdict(input: {
680
706
  operatorRoot: string;
681
707
  prNumber: number;
@@ -690,17 +716,33 @@ async function findCarriedVerdict(input: {
690
716
  if (shas === null) return null;
691
717
  const headIndex = shas.indexOf(input.headSha);
692
718
  if (headIndex < 0) return null;
693
- const earlier = shas.slice(0, headIndex).reverse().slice(0, CARRY_WALK_CAP);
694
- for (const sha of earlier) {
695
- const statuses = await input.readStatuses(input.operatorRoot, sha, {
696
- spawnFn: input.spawnFn,
697
- });
698
- if (statuses === null) return null;
699
- if (newestCarriedVerdict(statuses) !== undefined) {
700
- return { sha, statuses, older: earlier.slice(earlier.indexOf(sha) + 1) };
719
+ let end = headIndex;
720
+ walk: while (true) {
721
+ const earlier = shas.slice(0, end).reverse().slice(0, CARRY_WALK_CAP);
722
+ for (const sha of earlier) {
723
+ const statuses = await input.readStatuses(input.operatorRoot, sha, {
724
+ spawnFn: input.spawnFn,
725
+ });
726
+ if (statuses === null) return null;
727
+ if (newestCarriedVerdict(statuses) !== undefined) {
728
+ return {
729
+ sha,
730
+ statuses,
731
+ older: earlier.slice(earlier.indexOf(sha) + 1),
732
+ };
733
+ }
734
+ const newest = newestStatusInContext(statuses, COMMIT_STATUS_CONTEXT);
735
+ const held = newest === undefined ? null : heldVerdictSha(newest);
736
+ if (held !== null) {
737
+ const target = shas.findIndex((s) => s.startsWith(held));
738
+ if (target >= 0 && target < shas.indexOf(sha)) {
739
+ end = target + 1;
740
+ continue walk;
741
+ }
742
+ }
701
743
  }
744
+ return null;
702
745
  }
703
- return null;
704
746
  }
705
747
 
706
748
  // WHY the head's override holds: a human's `/pr-hero override` on this head is the decision for it. A
@@ -176,6 +176,7 @@ export async function evaluateCiAdmissionGate(input: {
176
176
  }
177
177
  const trustedActors = resolveCiTrustedActors({
178
178
  githubActor: process.env.GITHUB_ACTOR,
179
+ platformActor: process.env.CRYSK_PLATFORM_ACTOR,
179
180
  extra: config.ci_trusted_actors,
180
181
  });
181
182
  const allComments = [...reviewComments, ...issueComments];
@@ -387,7 +388,7 @@ export async function evaluateCiAdmissionGate(input: {
387
388
  advisoryCount: admissionVerdict.prior.advisory,
388
389
  });
389
390
  // S2: manual-required carries the last verdict like every other skip (publishCiSkip,
390
- // admissionSkipDecision); a carried red with every blocking finding answered turns green, unverified.
391
+ // admissionSkipDecision), except a green: Stage 2 #12 holds it pending for a manual review.
391
392
  const plan = planCiReviewManualRequired({
392
393
  prNumber,
393
394
  verdict: admissionVerdict,
@@ -0,0 +1,58 @@
1
+ import { writeFileSync } from "node:fs";
2
+ import path from "node:path";
3
+
4
+ export const FINDING_STATE_FILE = "finding-state.json";
5
+
6
+ // Which findings stay open after this run, under the ids that last across runs (R###). findings.json
7
+ // cannot say: it holds only this run's findings, renumbered each run, and a finding missing from it
8
+ // may simply not have been looked at. Only ids and statuses: nothing here can quote the customer's
9
+ // code, so it may leave the runner in metadata-only mode too.
10
+ export interface FindingStateRecord {
11
+ open: { id: string; status: string; tier: string }[];
12
+ // This run's finding id -> its stable id.
13
+ fresh: Record<string, string>;
14
+ // The stable ids this run verified gone. Absence never means resolved.
15
+ resolved: string[];
16
+ // The stable ids a stronger finding replaced this run, under a new id. Not fixed, so not resolved.
17
+ superseded: string[];
18
+ // Rows the state block's size cap left out, whose state is therefore unknown.
19
+ dropped: number;
20
+ }
21
+
22
+ export function buildFindingStateRecord(input: {
23
+ rows: readonly { id: string; status: string; tier: string }[];
24
+ freshFindingIds: readonly string[];
25
+ freshIds: readonly (string | undefined)[];
26
+ resolvedIds: readonly string[];
27
+ supersededIds: readonly string[];
28
+ dropped: number;
29
+ }): FindingStateRecord {
30
+ const fresh: Record<string, string> = {};
31
+ input.freshFindingIds.forEach((findingId, index) => {
32
+ const stable = input.freshIds[index];
33
+ if (stable !== undefined) fresh[findingId] = stable;
34
+ });
35
+ return {
36
+ open: input.rows.map(({ id, status, tier }) => ({ id, status, tier })),
37
+ fresh,
38
+ resolved: [...input.resolvedIds],
39
+ superseded: [...input.supersededIds],
40
+ dropped: input.dropped,
41
+ };
42
+ }
43
+
44
+ // The report to the platform runs as another process, so it reads this file. A failure to write only
45
+ // costs the platform this detail; it must not change the review's result.
46
+ export function writeFindingStateRecord(
47
+ runDir: string,
48
+ record: FindingStateRecord,
49
+ ): void {
50
+ try {
51
+ writeFileSync(
52
+ path.join(runDir, FINDING_STATE_FILE),
53
+ `${JSON.stringify(record)}\n`,
54
+ );
55
+ } catch {
56
+ // see above
57
+ }
58
+ }
@@ -0,0 +1,22 @@
1
+ import { writeFileSync } from "node:fs";
2
+ import path from "node:path";
3
+
4
+ export const GATE_RECORD_FILE = "gate.json";
5
+
6
+ // The count the `crysk` status is decided on: this run's blocking findings plus earlier ones still
7
+ // open. findings.json holds only this run's, so a same-head re-review there reads zero while the
8
+ // status stays red. The report to the platform runs as another process, so it reads this file. A
9
+ // failure to write only costs the platform the number; it must not change the review's result.
10
+ export function writeGateRecord(
11
+ runDir: string,
12
+ unresolvedBlocking: number,
13
+ ): void {
14
+ try {
15
+ writeFileSync(
16
+ path.join(runDir, GATE_RECORD_FILE),
17
+ `${JSON.stringify({ unresolved_blocking: unresolvedBlocking })}\n`,
18
+ );
19
+ } catch {
20
+ // see above
21
+ }
22
+ }
package/src/pr/inline.ts CHANGED
@@ -14,6 +14,7 @@
14
14
  import type { PrHeroFindingRef } from "#compare/compare";
15
15
  import { extractAnchor } from "#review/root-cause";
16
16
  import { diffRecordPath, splitDiffRecords } from "#review/size-gate";
17
+ import type { FindingStateRecord } from "./finding-state-record";
17
18
  import { claimFingerprint, type ParsedFindingMarker } from "./preflight";
18
19
 
19
20
  // The comparison ref plus the proof_refs posting needs to re-anchor an
@@ -447,6 +448,8 @@ export function buildPostPlan(input: {
447
448
  // ---------------------------------------------------------------------------
448
449
 
449
450
  export interface InlinePostOutcome {
451
+ // Absent when this post wrote no state block, so nothing can be said about findings across runs.
452
+ findingState?: FindingStateRecord;
450
453
  reviewOutcome: "posted" | "demoted";
451
454
  reviewFindingCount: number;
452
455
  // Always [] this slice (issues #16/#17): findings no longer POST as
package/src/pr/posting.ts CHANGED
@@ -21,6 +21,7 @@ import type { CiMode } from "#pr/preflight";
21
21
  import type { RereviewProvenance } from "#rereview/prepare";
22
22
  import type { FindingsDocument } from "#review/findings";
23
23
  import { log } from "#ui/primitives";
24
+ import { writeFindingStateRecord } from "./finding-state-record";
24
25
 
25
26
  export interface PostingStageResult {
26
27
  posted: InlinePostOutcome | null;
@@ -91,6 +92,9 @@ export async function postFindingsIfEnabled(input: {
91
92
  if (posted) {
92
93
  input.onDelivered?.();
93
94
  await writePostReceipt(input.runDir, input.pr, input.headSha, posted);
95
+ if (posted.findingState !== undefined) {
96
+ writeFindingStateRecord(input.runDir, posted.findingState);
97
+ }
94
98
  log(
95
99
  `posted: review ${posted.reviewOutcome} (${posted.reviewFindingCount} ` +
96
100
  `finding(s)), ${posted.outsideDiffCount} outside diff, ` +
@@ -24,6 +24,7 @@ import {
24
24
  findMarkedCommentId,
25
25
  IN_FLIGHT_TTL_MS,
26
26
  isInFlightCommitStatus,
27
+ isManualReviewHold,
27
28
  latestStatusInContext,
28
29
  type ParsedFindingMarker,
29
30
  parseFindingMarker,
@@ -573,6 +574,17 @@ function decideNext(
573
574
  (a) => a.finding.blocking && a.finding.live_on_head,
574
575
  );
575
576
  if (gate.state === "pending") {
577
+ // Stage 2 #12: a capped rule (the budget used up, or manual_only) held the head instead of carrying a
578
+ // green no review saw. No run will review it on its own, so waiting is wrong, and so is a routine
579
+ // forced review: a human decides between verifying the head and merging it unverified.
580
+ if (
581
+ isManualReviewHold({ state: gate.state, description: gate.description })
582
+ ) {
583
+ return {
584
+ next_action: "override-or-fix",
585
+ reason: `The gate holds this head for a manual review: the automatic review budget is used up, or the review policy is manual (ci_review_policy is manual_only), so no review read it and none will on its own. Comment ${commandHint(REVIEW_COMMAND, "")} to verify it, or ${commandHint(OVERRIDE_COMMAND, "")} to merge it unverified.`,
586
+ };
587
+ }
576
588
  if (gate.pending_in_flight) {
577
589
  return {
578
590
  next_action: "wait",
@@ -600,11 +612,21 @@ function decideNext(
600
612
  };
601
613
  }
602
614
  if (gate.state === "success") {
615
+ // PR #472/#475: a finding that lives only in the summary (outside the diff) has no thread, so nothing
616
+ // can be owed on it, but a done that does not name it let the loop merge without reading it. Every
617
+ // done below carries this note.
618
+ const summaryOnly = analyzed.filter(
619
+ (a) => a.finding.comment_id === null,
620
+ ).length;
621
+ const summaryNote =
622
+ summaryOnly === 0
623
+ ? ""
624
+ : ` ${summaryOnly} finding(s) live only in the summary comment (outside the diff, no thread to reply in); read them there before merging.`;
603
625
  // An override is a human's unlock of the head, so it stays done whatever the findings say.
604
626
  if (gate.override.active) {
605
627
  return {
606
628
  next_action: "done",
607
- reason: `The gate is green through an override by @${gate.override.by ?? "an unknown login"}; nothing is owed on this head.`,
629
+ reason: `The gate is green through an override by @${gate.override.by ?? "an unknown login"}; nothing is owed on this head.${summaryNote}`,
608
630
  };
609
631
  }
610
632
  // A partial review of this head (some reviewers failed) is not a finished review, and the
@@ -635,7 +657,7 @@ function decideNext(
635
657
  ) {
636
658
  return {
637
659
  next_action: "done",
638
- reason: `The gate is green on answered findings no review verified (${gate.description}); the PR is ready to merge, or comment ${commandHint(REVIEW_COMMAND, "")} for another review.`,
660
+ reason: `The gate is green on answered findings no review verified (${gate.description}); the PR is ready to merge, or comment ${commandHint(REVIEW_COMMAND, "")} for another review.${summaryNote}`,
639
661
  };
640
662
  }
641
663
  // #317: no review ran, so the reason must not read as a review that passed.
@@ -644,14 +666,12 @@ function decideNext(
644
666
  ) {
645
667
  return {
646
668
  next_action: "done",
647
- reason:
648
- "Every changed file on this head is excluded from review, so there was nothing to review; nothing is owed.",
669
+ reason: `Every changed file on this head is excluded from review, so there was nothing to review; nothing is owed.${summaryNote}`,
649
670
  };
650
671
  }
651
672
  return {
652
673
  next_action: "done",
653
- reason:
654
- "The review on this head passed the gate, and every finding on this head has a reply.",
674
+ reason: `The review on this head passed the gate, and every finding on this head has a reply.${summaryNote}`,
655
675
  };
656
676
  }
657
677
  // failure: the blocking findings on this head decide between triage, fix, and override.
@@ -719,7 +739,7 @@ function decideNext(
719
739
  next_action: "fix",
720
740
  reason:
721
741
  open === 0 && unseen === 0
722
- ? "Every live blocking finding is answered and a review rule skipped this head; push the fix. If a rule skips that push too, the gate reads the replies on it and can turn green, marked unverified; otherwise the review verifies it."
742
+ ? "Every live blocking finding is answered and a review rule skipped this head; push the fix. If a rule skips that push too, the gate reads the replies on it and can turn green, marked unverified, or, under a used-up budget or manual_only, hold the head for a manual review; otherwise the review verifies it."
723
743
  : `A live blocking finding is tagged applied, but ${open + unseen} blocking finding(s) are still open (deferred, misclassified, a dismissal not upheld, a reply at another head, or one this read cannot see), so replies alone will not unlock the carried red; push the fix, and answer or fix the rest.`,
724
744
  };
725
745
  }