fix(snapshot): gate folds - rejection wording, exact result enumeration, generated outputs list, artifact note

The snapshot rejection's fix names the apply, check, or merge step an input belongs to (merged-file and layering are refused by apply and check too). The action.yml result-output test asserts the enumerated values as an exact set, so a value dropped from the enumeration while still named in prose fails. The outputs-list generated region on the inputs reference now carries the snapshot results through renderOutputsList, replacing the hand-kept list beside it. The snapshot guide's fleet example says the uploaded directory holds redacted targets' full documents in the clear and points at the redaction guide's artifact-visibility note.

Author: Vivswan

.github/scripts/gen-docs.ts

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { REPO_RESULTS, type RepoResult } from "../../src/engine/orchestrate.js";
 import { MERGE_RESULT } from "../../src/flows/deliver.js";
+import { SNAPSHOT_RESULTS } from "../../src/flows/snapshot.js";
 import type { SectionDocs } from "../../src/sections/contract/docs.js";
 import {
   type SectionMeta,
@@ -239,8 +240,12 @@ const RESULT_DISPLAY: Record<RepoResult, "any mode" | "multi-repo only"> = {
 
 const WORST_OF = "; worst-of across targets in multi-repo mode";
 const CAN_ALSO_APPEAR = " can also appear";
-/** The merge-mode result, a value outside RepoResult, closes the enumeration. */
+/** The merge- and snapshot-mode results, values outside RepoResult, close the enumeration. */
 const MERGE_ONLY = `; \`${MERGE_RESULT}\` in mode: merge`;
+const SNAPSHOT_ONLY = `; ${[...SNAPSHOT_RESULTS]
+  .reverse()
+  .map((value) => `\`${value}\``)
+  .join(" / ")} in mode: snapshot`;
 
 export function renderOutputsList(results: readonly RepoResult[]): string {
   const ordered = (Object.keys(RESULT_DISPLAY) as RepoResult[]).filter((value) =>
@@ -254,7 +259,7 @@ export function renderOutputsList(results: readonly RepoResult[]): string {
   const lead = `${anyMode.join(" / ")}${WORST_OF}`;
   const withMulti =
     multiOnly.length === 0 ? lead : `${lead}, where ${multiOnly.join(" and ")}${CAN_ALSO_APPEAR}`;
-  return `${withMulti}${MERGE_ONLY}`;
+  return `${withMulti}${MERGE_ONLY}${SNAPSHOT_ONLY}`;
 }
 
 export type TaggedOperation = Pick<SectionOperation, "role" | "grade" | "permission"> & {
@@ -337,7 +342,7 @@ function outputsListRegion(name: string, heading: string): GeneratedRegion {
     body: new RegExp(
       String.raw`^(?:\x60[a-z]+\x60(?: / \x60[a-z]+\x60)*${escapeRe(WORST_OF)}(?:, where ` +
         String.raw`\x60[a-z]+\x60(?: and ` +
-        String.raw`\x60[a-z]+\x60)*${escapeRe(CAN_ALSO_APPEAR)})?(?:${escapeRe(MERGE_ONLY)})?)?$`,
+        String.raw`\x60[a-z]+\x60)*${escapeRe(CAN_ALSO_APPEAR)})?(?:${escapeRe(MERGE_ONLY)})?(?:${escapeRe(SNAPSHOT_ONLY)})?)?$`,
     ),
     render: () => renderOutputsList(REPO_RESULTS),
   };

docs/operate/snapshot.md

@@ -156,7 +156,7 @@ jobs:
 
 Copy the directory in as your `repos-dir` to bring the fleet under management, one reviewable file per repository. The step summary lists every target with its result and file, then one section table per target, and the `repos-result` output carries the per-repository results as JSON.
 
-Private and internal targets are redacted by default, exactly as in a multi-repo apply (see [private repositories](private-repositories.md)): their file is written like the others, but the public surfaces know them only as `private repository #N`, with the file name and every detail hidden. Their notes are in their file header; there is no report channel in snapshot mode.
+Private and internal targets are redacted by default, exactly as in a multi-repo apply (see [private repositories](private-repositories.md)): their file is written like the others, but the public surfaces know them only as `private repository #N`, with the file name and every detail hidden. Their notes are in their file header; there is no report channel in snapshot mode. The uploaded `snapshots` artifact therefore holds those targets' full documents in the clear, and an artifact inherits the admin repository's visibility, so on a public admin repository encrypt it or skip the upload (see [what redaction does and does not protect](private-repositories.md#what-redaction-does-and-does-not-protect)).
 
 ## Inputs in mode: snapshot
 

docs/reference/inputs.md

@@ -41,7 +41,7 @@ The discovery-only inputs apply to `repos: "*"`; the [multi-repo guide](../opera
 
 ## Outputs
 
-- `result`: <!-- BEGIN GENERATED: outputs-list (bun run build:docs; derived from REPO_RESULTS in src/engine/orchestrate.ts) -->`applied` / `partial` / `clean` / `drift` / `failed`; worst-of across targets in multi-repo mode, where `skipped` can also appear; `merged` in mode: merge<!-- END GENERATED: outputs-list -->. In `mode: snapshot` it reads `snapshot`, `partial`, or `failed`; the [snapshot guide](../operate/snapshot.md) has that table.
+- `result`: <!-- BEGIN GENERATED: outputs-list (bun run build:docs; derived from REPO_RESULTS in src/engine/orchestrate.ts) -->`applied` / `partial` / `clean` / `drift` / `failed`; worst-of across targets in multi-repo mode, where `skipped` can also appear; `merged` in mode: merge; `snapshot` / `partial` / `failed` in mode: snapshot<!-- END GENERATED: outputs-list -->. The [snapshot guide](../operate/snapshot.md) has the snapshot values' exit-code table.
 - `skipped-sections`: the sections skipped for missing permissions under `on-missing-permission: warn`, comma-separated (a deduped union across targets in multi-repo mode).
 - `repos-result`: multi-repo mode only, a JSON map of `owner/name` to `{result, source, skippedSections}`. A redacted private target is keyed by its `private repository #N` placeholder instead of its slug; see [Private repositories](../operate/private-repositories.md).
 

src/problem.ts

@@ -413,7 +413,7 @@ export function describeProblem(problem: Problem): string {
         `the ${quoteList(problem.inputs)} input(s) do not apply to mode: snapshot, which only reads the ` +
         "target repositories' live settings into snapshot-file or snapshot-dir: it applies no " +
         "document, folds no layers, and delivers no report. Remove the input(s), or move them to " +
-        "the apply or check step that runs the snapshot"
+        "the apply, check, or merge step they belong to"
       );
     case "input-snapshot-destination-missing":
       return 'mode: snapshot needs exactly one of the "snapshot-file" input (one repository\'s settings written to that file) or the "snapshot-dir" input (one <owner>/<name>.yml per repos or repos-dir target under that directory). Set one of them';

test/action/action-yml.test.ts

@@ -56,14 +56,20 @@ describe("input declarations <-> discovery defaults", () => {
 });
 
 describe("output declarations", () => {
-  test("the result description mentions every RepoResult value, the merge result, and the snapshot results", () => {
-    // MERGE_RESULT and SNAPSHOT_RESULTS are the values outside REPO_RESULTS (neither mode has a target).
-    const missing = [...REPO_RESULTS, MERGE_RESULT, ...SNAPSHOT_RESULTS].filter(
-      (value) => !OUTPUT_DECLS.result.description.includes(value),
+  test("the result description enumerates exactly the RepoResult values, the merge result, and the snapshot results", () => {
+    // The enumerated values are the `a | b | c` chains; a value named only in prose ("in mode: snapshot") does not count.
+    const { description } = OUTPUT_DECLS.result;
+    const enumerated = (description.match(/[a-z]+(?: \| [a-z]+)+/g) ?? []).flatMap((chain) =>
+      chain.split(" | "),
+    );
+    expect(new Set(enumerated)).toEqual(
+      new Set([...REPO_RESULTS.filter((value) => value !== "skipped"), ...SNAPSHOT_RESULTS]),
+    );
+    expect(description).toContain("where skipped can also appear");
+    expect(description).toContain(`${MERGE_RESULT} in mode: merge`);
+    // SNAPSHOT_RESULTS is worst-first; the description reads best-first like the RepoResult chain.
+    expect(description).toContain(
+      `${[...SNAPSHOT_RESULTS].reverse().join(" | ")} in mode: snapshot`,
     );
-    expect(
-      missing,
-      `the "result" output description omits result value(s): ${missing.join(", ")}`,
-    ).toEqual([]);
   });
 });

test/action/run.test.ts

@@ -871,7 +871,7 @@ describe("run in mode: snapshot", () => {
       'error: the "settings-file" input(s) do not apply to mode: snapshot, which only reads the ' +
         "target repositories' live settings into snapshot-file or snapshot-dir: it applies no " +
         "document, folds no layers, and delivers no report. Remove the input(s), or move them to " +
-        "the apply or check step that runs the snapshot",
+        "the apply, check, or merge step they belong to",
       "result: failed",
     ]);
   });

test/problem.test.ts

@@ -100,7 +100,7 @@ const SPECIMENS = {
     'the "settings-file", "layering" input(s) do not apply to mode: snapshot, which only reads the ' +
       "target repositories' live settings into snapshot-file or snapshot-dir: it applies no " +
       "document, folds no layers, and delivers no report. Remove the input(s), or move them to " +
-      "the apply or check step that runs the snapshot",
+      "the apply, check, or merge step they belong to",
   ],
   "input-snapshot-destination-missing": [
     { code: "input-snapshot-destination-missing" },

test/scripts/gen-docs.test.ts

@@ -280,12 +280,12 @@ describe("renderPatCell", () => {
 });
 
 describe("renderOutputsList", () => {
-  test("lists the any-mode values in display order, then the multi-repo-only ones, then the merge result", () => {
+  test("lists the any-mode values in display order, then the multi-repo-only ones, then the merge and snapshot results", () => {
     expect(renderOutputsList(REPO_RESULTS)).toBe(
-      "`applied` / `partial` / `clean` / `drift` / `failed`; worst-of across targets in multi-repo mode, where `skipped` can also appear; `merged` in mode: merge",
+      "`applied` / `partial` / `clean` / `drift` / `failed`; worst-of across targets in multi-repo mode, where `skipped` can also appear; `merged` in mode: merge; `snapshot` / `partial` / `failed` in mode: snapshot",
     );
     expect(renderOutputsList(["failed", "applied"])).toBe(
-      "`applied` / `failed`; worst-of across targets in multi-repo mode; `merged` in mode: merge",
+      "`applied` / `failed`; worst-of across targets in multi-repo mode; `merged` in mode: merge; `snapshot` / `partial` / `failed` in mode: snapshot",
     );
   });
 });