feat(snapshot): collaborators and teams read back

Both membership sections declare snapshot(). Collaborators reads the direct collaborators and the pending username invitations back as entries under the delete default; teams lists the teams with access through a new GET /repos/{owner}/{repo}/teams endpoint and reads each team's role through the same probe plan() compares against, so a custom repository role reads back by name.

Both read roles through the shared permissionForRole lens. Where it answers undefined (a custom role named "push" or "pull", which the settings vocabulary reads as write or read), collaborators fails the snapshot loudly, since dropping the entry would plan a removal, and teams omits the team with a note, since the section never removes an undeclared team. The enrolment rows prove plan() converges on every emitted value.

Not declared, each with a note: the repository owner (plan() never manages them), email invitations (plan() leaves them alone), expired invitations (a declared one would be cancelled and re-sent), team access granted at the organization or enterprise level (declaring it would grant direct access), and a team whose role the probe cannot read.

The e2e mock serves the team listing from the seeded team access; the trimmed OpenAPI spec picks the path up through USED_PATHS. No e2e mode issues snapshot reads yet, so the listing has no scenario and the endpoint-coverage tripwire reports it cold until one exists.

Author: settings-as-code-release

COVERAGE.md

@@ -35,8 +35,8 @@ The tenet: this action can control everything about a repository and nothing abo
 | [GitHub Pages](https://docs.github.com/en/rest/pages/pages) (build_type, source, cname, https_enforced and any PUT field GitHub adds; pages: null disables the site) | `pages` | POST /repos/{owner}/{repo}/pages (create accepts only build_type/source) then PUT for the rest; existing sites get straight PUT passthrough; pages: null issues DELETE, mirroring branches' protection: null. In a mode: merge fold, pages: null over a lower layer's pages declaration removes the key from the merged document instead (the layering guide owns that rule); a multi-repo defaults-file never merges into a target's file. The Enterprise Cloud site-visibility boolean `public` (public vs repo-members-only) rides the PUT passthrough too - the dotcom docs omit it but the GHEC flavor documents it, and the GET echoes it in both, so declaring it applies and check-verifies today. Snapshot reads the live site back on the declared keys; a repository without Pages is omitted rather than declared null. |
 | [Code scanning default setup](https://docs.github.com/en/rest/code-scanning/code-scanning) | `code_scanning_default_setup` | GET/PATCH /repos/{owner}/{repo}/code-scanning/default-setup, PATCH body verbatim (state, query_suite, languages, runner_type, runner_label, threat_model). A 202 answer means GitHub rolls the change out in a configuration run, which the log names. Check compares declared keys only, languages as a set. Needs GitHub Advanced Security on private repositories; a 403 can mean that (or an archived repository) rather than a missing permission. Snapshot reads the GET body back on the declared keys; a null the slice does not take (a not-configured setup's runner_type) is omitted. |
 | [Code quality setup](https://docs.github.com/en/rest/code-quality/code-quality) | `code_quality_setup` | GET/PATCH /repos/{owner}/{repo}/code-quality/setup, PATCH body verbatim (state, languages, runner_type, runner_label, ai_findings_option), the near field-for-field mirror of code_scanning_default_setup. A 202 answer means GitHub rolls the change out in a configuration run, which the log names; a 409 means a configuration run is already in progress (re-run the workflow after it finishes); a 403 can mean code quality is unavailable on the repository or the repository is archived, rather than a missing permission, and a 422 (the change cannot be applied) carries GitHub's message verbatim. Check compares declared keys only, languages as a set. ASSUMPTION: the GET is graded as a plain read under the Administration permission, mirroring code scanning - the fine-grained grading of these endpoints is not verified against production. The sibling /code-quality/findings endpoints are read-only and stay out of scope. Snapshot reads the GET body back on the declared keys; a null the slice does not take (a not-configured setup's runner_type) is omitted. |
-| [Collaborators](https://docs.github.com/en/rest/collaborators/collaborators) (direct) | `collaborators` | PUT/DELETE /repos/{owner}/{repo}/collaborators/{username} (affiliation=direct); pending invitations reconciled alongside via GET /repos/{owner}/{repo}/invitations and PATCH/DELETE /repos/{owner}/{repo}/invitations/{invitation_id}: a declared user's matching pending invitation converges, a stale permission is PATCHed in place (a declared custom role cannot be verified against an invitation - the standard-roles enum - so the invitation is kept with a note), an expired invitation is cancelled and re-sent, and undeclared pending invitations follow the section's one undeclared policy (email invitations, which no username can declare, are noted and left untouched); vocabulary mapping push<->write, pull<->read for check mode; custom org role names pass through; undeclared direct collaborators REMOVED by default (kept as notes under the wrapped `_undeclared: keep` form), owner never touched; new users get invitations. |
-| [Team repository permissions](https://docs.github.com/en/rest/teams/teams) (org repos) | `teams` | PUT /orgs/{org}/teams/{slug}/repos/{owner}/{repo}; probes GET /orgs/{owner} and no-ops with a note on personal accounts (404 only; 403/5xx still fail). Both modes probe each team's access with the v3.repository media type to read role_name, and the grant is issued only when the team lacks access or its live role diverges. |
+| [Collaborators](https://docs.github.com/en/rest/collaborators/collaborators) (direct) | `collaborators` | PUT/DELETE /repos/{owner}/{repo}/collaborators/{username} (affiliation=direct); pending invitations reconciled alongside via GET /repos/{owner}/{repo}/invitations and PATCH/DELETE /repos/{owner}/{repo}/invitations/{invitation_id}: a declared user's matching pending invitation converges, a stale permission is PATCHed in place (a declared custom role cannot be verified against an invitation - the standard-roles enum - so the invitation is kept with a note), an expired invitation is cancelled and re-sent, and undeclared pending invitations follow the section's one undeclared policy (email invitations, which no username can declare, are noted and left untouched); vocabulary mapping push<->write, pull<->read for check mode; custom org role names pass through; undeclared direct collaborators REMOVED by default (kept as notes under the wrapped `_undeclared: keep` form), owner never touched; new users get invitations. Snapshot reads the direct collaborators and the pending username invitations back as entries under the delete default, each role through the inverse mapping (write -> push, read -> pull, custom role names verbatim); the repository owner, email invitations, and expired invitations are noted, not declared, and a live role no declaration plans as (a custom role named "push" or "pull") fails the snapshot loudly. |
+| [Team repository permissions](https://docs.github.com/en/rest/teams/teams) (org repos) | `teams` | PUT /orgs/{org}/teams/{slug}/repos/{owner}/{repo}; probes GET /orgs/{owner} and no-ops with a note on personal accounts (404 only; 403/5xx still fail). Both modes probe each team's access with the v3.repository media type to read role_name, and the grant is issued only when the team lacks access or its live role diverges. Snapshot lists the teams with access (GET /repos/{owner}/{repo}/teams) and reads each team's role through the same probe, so a custom role reads back by name; noted, not declared: access granted at the organization or enterprise level, a role the probe does not report, and a role no declaration plans as (a custom role named "push" or "pull"). A personal account snapshots nothing. |
 | [Milestones](https://docs.github.com/en/rest/issues/milestones) | `milestones` | POST/PATCH/DELETE /repos/{owner}/{repo}/milestones, matched by title, declared-keys-only (description/state untouched unless declared); undeclared milestones kept by default and surfaced as notes, because deleting a milestone DETACHES it from every issue carrying it - the wrapped `_undeclared: delete` form opts into exactly that. Snapshot reads every milestone, open and closed, back as entries under the keep default. |
 | [Interaction limits](https://docs.github.com/en/rest/interactions/repos) | `interaction_limits` | GET/PUT/DELETE /repos/{owner}/{repo}/interaction-limits, plus the two routed keys below. Limits self-expire (expiry tops out at six_months), so apply re-arms the declared limit on EVERY run and check mode reports drift once it lapses - schedule apply more often than the chosen expiry to keep it armed. The declared expiry is write-only (GitHub reads back only the computed expires_at), so check verifies the limit value, not the duration. `interaction_limits: null` clears a live repo-level limit - the base limit only, never the cap or bypass list below. In a mode: merge fold, interaction_limits: null over a lower layer's declaration removes the key from the merged document instead, mirroring pages: null. A 409 means an organization- or user-level limit overrides the repository's; writes surface that as a note, not a failure, while check mode still reports a mismatched declaration as drift - the org is the place to change it. `pull_request_creation_cap` routes to GET/PATCH /repos/{owner}/{repo}/interaction-limits/pulls/creation-cap: persistent desired state with no self-expiry (enabled plus max_open_pull_requests 1-1000, read back verbatim), so check diffs it exactly and apply PATCHes only on divergence - no re-arm. Where the cap is unavailable the endpoints answer 405, which apply surfaces as a note (like the 409) and check as honest drift. `pull_request_creation_bypass` routes to GET/PUT/DELETE /repos/{owner}/{repo}/interaction-limits/pulls/bypass-list and reconciles: apply DELETEs only the undeclared logins and then PUTs only the missing ones ({users: [logins]}, compared case-insensitively; removals go first because the list holds at most 100 users, which also caps the declaration), never a wholesale replace; a declared empty list removes everyone. Snapshot reads back the repository-level limit (an inherited one is noted, not declared, and the expiry duration is not readable), the cap when the feature exists and is enabled, and the bypass list when it has members. |
 | [Actions variables](https://docs.github.com/en/rest/actions/variables) | `actions_variables` | GET/POST /repos/{owner}/{repo}/actions/variables and PATCH/DELETE /repos/{owner}/{repo}/actions/variables/{name}: plain-text repository variables, upserted by name. Names are case-insensitive (GitHub stores them uppercased regardless of how they are entered), so matching and duplicate rejection compare uppercased names. Values read back in full, which is what makes exact check-mode diffing possible; undeclared variables are DELETED by default, kept as notes under the wrapped `_undeclared: keep` form. The list endpoint caps per_page at 30 (not the usual 100), which the page loop honors so a large inventory is never truncated. Secrets are write-only material and deliberately NOT this section: they live in the `actions_secrets` section above. Snapshot reads the variables back as name and value entries under the delete default. |

docs/reference/sections.md

@@ -26,7 +26,7 @@ Every top-level key a settings file can declare, one row per section: the endpoi
 | `code_scanning_default_setup` | code scanning default setup | Administration or Code scanning alerts: write | untouched | `state`, `query_suite`, `languages`; needs Advanced Security on private repositories |
 | `code_quality_setup` | code-quality setup | Administration: write | untouched | `state`, `languages`, runner and AI-findings options; a 202 means GitHub rolls the change out in a configuration run; needs code quality available on the repository |
 | `collaborators` | direct collaborators + pending invitations | Administration: write | deleted (settable) | invitations for new users, pending ones reconciled (stale permission updated, expired re-sent, undeclared cancelled); the repository owner is never touched |
-| `teams` | org team repo permissions | Members: read (org permission) + Administration: write | untouched | org repos only, skipped with a notice on personal accounts |
+| `teams` | org team repo permissions + repo team list | Members: read (org permission) + Administration: write | untouched | org repos only, skipped with a notice on personal accounts |
 | `milestones` | milestones | Issues: write | kept (settable) | upsert by title; deleting a milestone detaches it from every issue carrying it, which is why keep is the default |
 | `interaction_limits` | interaction-limits + pulls creation-cap/bypass-list | Administration: write | untouched | re-arms the self-expiring limit every apply run; `null` clears it (base limit only); a 409 (org/user-level limit overrides) becomes a note; the PR creation cap is persistent (PATCHed only on divergence, 405 where unavailable) and its bypass logins reconcile add/remove |
 | `actions_variables` | Actions variables CRUD | Variables: write | deleted (settable) | plain-text variables upserted by name (case-insensitive); values read back in full, so check mode diffs them exactly |

src/sections/collaborators/collaborators.docs.yml

@@ -18,6 +18,11 @@ coverage:
       custom org role names pass through; undeclared direct collaborators REMOVED by default (kept
       as notes under the wrapped `_undeclared: keep` form), owner never touched; new users get
       invitations.
+      Snapshot reads the direct collaborators and the pending username invitations back as entries
+      under the delete default, each role through the inverse mapping (write -> push, read -> pull,
+      custom role names verbatim); the repository owner, email invitations, and expired invitations
+      are noted, not declared, and a live role no declaration plans as (a custom role named "push"
+      or "pull") fails the snapshot loudly.
 schema:
   SettingsFile.collaborators: >-
     Direct collaborators, with pending invitations reconciled alongside; undeclared ones are REMOVED

src/sections/collaborators/collaborators.test.ts

@@ -13,6 +13,8 @@ const LIST = "GET /repos/o/r/collaborators?affiliation=direct&per_page=100&page=
 const INVITATIONS = "GET /repos/o/r/invitations?per_page=100&page=1";
 const plan = (api: MockApi, desired: Parameters<typeof collaboratorsSection.plan>[1]) =>
   collaboratorsSection.plan(planContext(collaboratorsSection, api, REPO), desired);
+const snapshot = (api: MockApi) =>
+  collaboratorsSection.snapshot(planContext(collaboratorsSection, api, REPO));
 const NO_SECRETS = {
   resolveSecret: (): string => {
     throw new Error("no secrets");
@@ -326,4 +328,88 @@ describe("collaborators", () => {
     ctx.read.list.probeAbsent;
     expect(typeof ctx.read.listInvitations.listAll).toBe("function");
   });
+
+  describe("snapshot", () => {
+    test("reads collaborators then pending invitations back under the delete default; the owner, an expired invitation, and an email invitation are noted, not declared", async () => {
+      const api = new MockApi({
+        [LIST]: {
+          data: [
+            { login: "O", role_name: "admin" },
+            { login: "alice", role_name: "write" },
+            { login: "bob", role_name: "read" },
+            { login: "carol", role_name: "security-team" },
+          ],
+        },
+        [INVITATIONS]: {
+          data: [
+            { id: 7, invitee: { login: "dave" }, permissions: "write", expired: false },
+            { id: 8, invitee: { login: "erin" }, permissions: "read", expired: true },
+            { id: 9, invitee: null, permissions: "read", expired: false },
+          ],
+        },
+      });
+      expect(await snapshot(api)).toEqual({
+        value: {
+          _undeclared: "delete",
+          entries: [
+            { username: "alice", permission: "push" },
+            { username: "bob", permission: "pull" },
+            { username: "carol", permission: "security-team" },
+            { username: "dave", permission: "push" },
+          ],
+        },
+        notes: [
+          "collaborators[O]: the repository owner's access is implicit and never managed, so it is not declared",
+          "collaborators[erin]: the pending invitation has expired, so it is not declared; apply cancels it - add the entry to re-invite them",
+          "invitation 9 was sent by email, so no username can declare it; not declared, and apply leaves it untouched",
+        ],
+      });
+      expect(api.calls.map((c) => `${c.method} ${c.path}`)).toEqual([LIST, INVITATIONS]);
+    });
+
+    test("only the owner, an expired invitation, and an email invitation snapshot as nothing to declare; the expired note says apply leaves it", async () => {
+      const api = new MockApi({
+        [LIST]: { data: [{ login: "o", role_name: "admin" }] },
+        [INVITATIONS]: {
+          data: [
+            { id: 8, invitee: { login: "erin" }, permissions: "read", expired: true },
+            { id: 9, invitee: null, permissions: "read", expired: false },
+          ],
+        },
+      });
+      expect(await snapshot(api)).toEqual({
+        value: undefined,
+        notes: [
+          "collaborators[o]: the repository owner's access is implicit and never managed, so it is not declared",
+          "collaborators[erin]: the pending invitation has expired, so it is not declared; nothing else is declared, so the section is omitted and apply leaves it - declare the entry to re-invite them",
+          "invitation 9 was sent by email, so no username can declare it; not declared, and apply leaves it untouched",
+        ],
+      });
+    });
+
+    test("a collaborator or invitation without a role, or with a role no declaration plans as, fails loudly instead of declaring a guess", async () => {
+      const roleless = new MockApi({
+        [LIST]: { data: [{ login: "alice" }] },
+        [INVITATIONS]: { data: [] },
+      });
+      await expect(snapshot(roleless)).rejects.toThrow(
+        "collaborators[alice]: GitHub reported no role_name for this collaborator, so their permission cannot be read back",
+      );
+      const blankInvitation = new MockApi({
+        [LIST]: { data: [] },
+        [INVITATIONS]: { data: [{ id: 7, invitee: { login: "dave" }, expired: false }] },
+      });
+      await expect(snapshot(blankInvitation)).rejects.toThrow(
+        "collaborators[dave]: GitHub reported no permissions on the pending invitation, so it cannot be read back",
+      );
+      // A custom role named "push": declaring "push" plans the write role, so the entry can never converge.
+      const collision = new MockApi({
+        [LIST]: { data: [{ login: "frank", role_name: "push" }] },
+        [INVITATIONS]: { data: [] },
+      });
+      await expect(snapshot(collision)).rejects.toThrow(
+        'collaborators[frank]: the live role "push" has no declaration that plans as itself ("push" in a settings file means the "write" role), so it cannot be read back',
+      );
+    });
+  });
 });