@vivswan/github-settings-as-code 2.0.1-main.1090.g15ef0c9 → 2.0.1-main.1110.g63435fc

package/lib/pkg/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { C as SNAPSHOT_ONLY_INPUTS, E as parseSnapshotFileConfig, F as concludeMerge, I as concludeRun, Kt as redactRanges, L as failRun, Rt as GithubApi, S as SNAPSHOT_INPUTS, T as parseConfig, U as PRIVATE_REPORT_CHANNELS, Wt as maskRegistry, _ as INPUT_DECLS, d as runSnapshot, f as runSingle, j as readSettingsFile, k as runMulti, o as snapshotRepository, pt as SECTIONS, s as validateSettings, t as runMerge, tt as describeProblem, u as concludeSnapshot, v as MERGE_INPUTS, y as MERGE_ONLY_INPUTS, yt as sectionGrant } from "./src-BhuD5Ycj.js";
+import { C as SNAPSHOT_ONLY_INPUTS, E as parseSnapshotFileConfig, F as concludeMerge, I as concludeRun, Kt as redactRanges, L as failRun, Rt as GithubApi, S as SNAPSHOT_INPUTS, T as parseConfig, U as PRIVATE_REPORT_CHANNELS, Wt as maskRegistry, _ as INPUT_DECLS, d as runSnapshot, f as runSingle, j as readSettingsFile, k as runMulti, o as snapshotRepository, pt as SECTIONS, s as validateSettings, t as runMerge, tt as describeProblem, u as concludeSnapshot, v as MERGE_INPUTS, y as MERGE_ONLY_INPUTS, yt as sectionGrant } from "./src-B13lb6Pp.js";
 import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { ResultAsync, err, ok } from "neverthrow";

package/lib/pkg/index.d.ts

@@ -2307,6 +2307,22 @@ declare const GRAPHQL_OPS: {
       repo: string;
     } | undefined;
   };
+  readonly pinsSnapshot: {
+    readonly name: "EnvironmentPinsSnapshot";
+    readonly kind: "read";
+    readonly query: "query EnvironmentPinsSnapshot($owner: String!, $repo: String!, $cursor: String) { repository(owner: $owner, name: $repo) { pinnedEnvironments(first: 100, after: $cursor) { nodes { position environment { name } } pageInfo { hasNextPage endCursor } } } }";
+    readonly connection: {
+      readonly path: readonly ["repository", "pinnedEnvironments"];
+    };
+    readonly outcomes: {
+      readonly ok: "the pinned environments with their 1-based positions, for the snapshot";
+    };
+  } & {
+    readonly _variables?: {
+      owner: string;
+      repo: string;
+    } | undefined;
+  };
   readonly pin: {
     readonly name: "PinEnvironment";
     readonly kind: "write";
@@ -2428,6 +2444,22 @@ declare const GRAPHQL: {
       repo: string;
     } | undefined;
   };
+  readonly rulesSnapshot: {
+    readonly name: "BranchProtectionRulesSnapshot";
+    readonly kind: "read";
+    readonly connection: {
+      readonly path: readonly ["repository", "branchProtectionRules"];
+    };
+    readonly outcomes: {
+      readonly ok: "the repository's classic branch protection rules, for the snapshot";
+    };
+    readonly query: "query BranchProtectionRulesSnapshot($owner: String!, $repo: String!, $cursor: String) {\n  repository(owner: $owner, name: $repo) {\n    branchProtectionRules(first: 100, after: $cursor) {\n      nodes {\n        id\n        pattern\n        isAdminEnforced\n        requiresLinearHistory\n        allowsForcePushes\n        allowsDeletions\n        blocksCreations\n        requiresConversationResolution\n        lockBranch\n        lockAllowsFetchAndMerge\n        requiresCommitSignatures\n        requiresStatusChecks\n        requiresStrictStatusChecks\n        requiredStatusCheckContexts\n        requiresApprovingReviews\n        requiredApprovingReviewCount\n        requiresCodeOwnerReviews\n        dismissesStaleReviews\n        requireLastPushApproval\n        requiresDeployments\n        requiredDeploymentEnvironments\n        bypassForcePushAllowances(first: 100) {\n          nodes {\n            actor {\n              __typename\n              ... on User { login }\n              ... on Team { combinedSlug }\n              ... on App { slug }\n            }\n          }\n          pageInfo { hasNextPage }\n        }\n      }\n      pageInfo { hasNextPage endCursor }\n    }\n  }\n}";
+  } & {
+    readonly _variables?: {
+      owner: string;
+      repo: string;
+    } | undefined;
+  };
   readonly repoLookup: {
     readonly name: "BranchProtectionRepository";
     readonly kind: "read";
@@ -3935,6 +3967,22 @@ declare const byKey: {
           repo: string;
         } | undefined;
       };
+      readonly pinsSnapshot: {
+        readonly name: "EnvironmentPinsSnapshot";
+        readonly kind: "read";
+        readonly query: "query EnvironmentPinsSnapshot($owner: String!, $repo: String!, $cursor: String) { repository(owner: $owner, name: $repo) { pinnedEnvironments(first: 100, after: $cursor) { nodes { position environment { name } } pageInfo { hasNextPage endCursor } } } }";
+        readonly connection: {
+          readonly path: readonly ["repository", "pinnedEnvironments"];
+        };
+        readonly outcomes: {
+          readonly ok: "the pinned environments with their 1-based positions, for the snapshot";
+        };
+      } & {
+        readonly _variables?: {
+          owner: string;
+          repo: string;
+        } | undefined;
+      };
       readonly pin: {
         readonly name: "PinEnvironment";
         readonly kind: "write";
@@ -4134,6 +4182,22 @@ declare const byKey: {
           repo: string;
         } | undefined;
       };
+      readonly pinsSnapshot: {
+        readonly name: "EnvironmentPinsSnapshot";
+        readonly kind: "read";
+        readonly query: "query EnvironmentPinsSnapshot($owner: String!, $repo: String!, $cursor: String) { repository(owner: $owner, name: $repo) { pinnedEnvironments(first: 100, after: $cursor) { nodes { position environment { name } } pageInfo { hasNextPage endCursor } } } }";
+        readonly connection: {
+          readonly path: readonly ["repository", "pinnedEnvironments"];
+        };
+        readonly outcomes: {
+          readonly ok: "the pinned environments with their 1-based positions, for the snapshot";
+        };
+      } & {
+        readonly _variables?: {
+          owner: string;
+          repo: string;
+        } | undefined;
+      };
       readonly pin: {
         readonly name: "PinEnvironment";
         readonly kind: "write";
@@ -4382,6 +4446,22 @@ declare const byKey: {
           repo: string;
         } | undefined;
       };
+      readonly pinsSnapshot: {
+        readonly name: "EnvironmentPinsSnapshot";
+        readonly kind: "read";
+        readonly query: "query EnvironmentPinsSnapshot($owner: String!, $repo: String!, $cursor: String) { repository(owner: $owner, name: $repo) { pinnedEnvironments(first: 100, after: $cursor) { nodes { position environment { name } } pageInfo { hasNextPage endCursor } } } }";
+        readonly connection: {
+          readonly path: readonly ["repository", "pinnedEnvironments"];
+        };
+        readonly outcomes: {
+          readonly ok: "the pinned environments with their 1-based positions, for the snapshot";
+        };
+      } & {
+        readonly _variables?: {
+          owner: string;
+          repo: string;
+        } | undefined;
+      };
       readonly pin: {
         readonly name: "PinEnvironment";
         readonly kind: "write";
@@ -4559,6 +4639,22 @@ declare const byKey: {
           repo: string;
         } | undefined;
       };
+      readonly rulesSnapshot: {
+        readonly name: "BranchProtectionRulesSnapshot";
+        readonly kind: "read";
+        readonly connection: {
+          readonly path: readonly ["repository", "branchProtectionRules"];
+        };
+        readonly outcomes: {
+          readonly ok: "the repository's classic branch protection rules, for the snapshot";
+        };
+        readonly query: "query BranchProtectionRulesSnapshot($owner: String!, $repo: String!, $cursor: String) {\n  repository(owner: $owner, name: $repo) {\n    branchProtectionRules(first: 100, after: $cursor) {\n      nodes {\n        id\n        pattern\n        isAdminEnforced\n        requiresLinearHistory\n        allowsForcePushes\n        allowsDeletions\n        blocksCreations\n        requiresConversationResolution\n        lockBranch\n        lockAllowsFetchAndMerge\n        requiresCommitSignatures\n        requiresStatusChecks\n        requiresStrictStatusChecks\n        requiredStatusCheckContexts\n        requiresApprovingReviews\n        requiredApprovingReviewCount\n        requiresCodeOwnerReviews\n        dismissesStaleReviews\n        requireLastPushApproval\n        requiresDeployments\n        requiredDeploymentEnvironments\n        bypassForcePushAllowances(first: 100) {\n          nodes {\n            actor {\n              __typename\n              ... on User { login }\n              ... on Team { combinedSlug }\n              ... on App { slug }\n            }\n          }\n          pageInfo { hasNextPage }\n        }\n      }\n      pageInfo { hasNextPage endCursor }\n    }\n  }\n}";
+      } & {
+        readonly _variables?: {
+          owner: string;
+          repo: string;
+        } | undefined;
+      };
       readonly repoLookup: {
         readonly name: "BranchProtectionRepository";
         readonly kind: "read";
@@ -4736,6 +4832,22 @@ declare const byKey: {
           repo: string;
         } | undefined;
       };
+      readonly rulesSnapshot: {
+        readonly name: "BranchProtectionRulesSnapshot";
+        readonly kind: "read";
+        readonly connection: {
+          readonly path: readonly ["repository", "branchProtectionRules"];
+        };
+        readonly outcomes: {
+          readonly ok: "the repository's classic branch protection rules, for the snapshot";
+        };
+        readonly query: "query BranchProtectionRulesSnapshot($owner: String!, $repo: String!, $cursor: String) {\n  repository(owner: $owner, name: $repo) {\n    branchProtectionRules(first: 100, after: $cursor) {\n      nodes {\n        id\n        pattern\n        isAdminEnforced\n        requiresLinearHistory\n        allowsForcePushes\n        allowsDeletions\n        blocksCreations\n        requiresConversationResolution\n        lockBranch\n        lockAllowsFetchAndMerge\n        requiresCommitSignatures\n        requiresStatusChecks\n        requiresStrictStatusChecks\n        requiredStatusCheckContexts\n        requiresApprovingReviews\n        requiredApprovingReviewCount\n        requiresCodeOwnerReviews\n        dismissesStaleReviews\n        requireLastPushApproval\n        requiresDeployments\n        requiredDeploymentEnvironments\n        bypassForcePushAllowances(first: 100) {\n          nodes {\n            actor {\n              __typename\n              ... on User { login }\n              ... on Team { combinedSlug }\n              ... on App { slug }\n            }\n          }\n          pageInfo { hasNextPage }\n        }\n      }\n      pageInfo { hasNextPage endCursor }\n    }\n  }\n}";
+      } & {
+        readonly _variables?: {
+          owner: string;
+          repo: string;
+        } | undefined;
+      };
       readonly repoLookup: {
         readonly name: "BranchProtectionRepository";
         readonly kind: "read";
@@ -4922,6 +5034,22 @@ declare const byKey: {
           repo: string;
         } | undefined;
       };
+      readonly rulesSnapshot: {
+        readonly name: "BranchProtectionRulesSnapshot";
+        readonly kind: "read";
+        readonly connection: {
+          readonly path: readonly ["repository", "branchProtectionRules"];
+        };
+        readonly outcomes: {
+          readonly ok: "the repository's classic branch protection rules, for the snapshot";
+        };
+        readonly query: "query BranchProtectionRulesSnapshot($owner: String!, $repo: String!, $cursor: String) {\n  repository(owner: $owner, name: $repo) {\n    branchProtectionRules(first: 100, after: $cursor) {\n      nodes {\n        id\n        pattern\n        isAdminEnforced\n        requiresLinearHistory\n        allowsForcePushes\n        allowsDeletions\n        blocksCreations\n        requiresConversationResolution\n        lockBranch\n        lockAllowsFetchAndMerge\n        requiresCommitSignatures\n        requiresStatusChecks\n        requiresStrictStatusChecks\n        requiredStatusCheckContexts\n        requiresApprovingReviews\n        requiredApprovingReviewCount\n        requiresCodeOwnerReviews\n        dismissesStaleReviews\n        requireLastPushApproval\n        requiresDeployments\n        requiredDeploymentEnvironments\n        bypassForcePushAllowances(first: 100) {\n          nodes {\n            actor {\n              __typename\n              ... on User { login }\n              ... on Team { combinedSlug }\n              ... on App { slug }\n            }\n          }\n          pageInfo { hasNextPage }\n        }\n      }\n      pageInfo { hasNextPage endCursor }\n    }\n  }\n}";
+      } & {
+        readonly _variables?: {
+          owner: string;
+          repo: string;
+        } | undefined;
+      };
       readonly repoLookup: {
         readonly name: "BranchProtectionRepository";
         readonly kind: "read";
@@ -5013,7 +5141,7 @@ declare const byKey: {
       };
     }>): Promise<{
       value: undefined;
-      notes: never[];
+      notes: string[];
     } | {
       value: {
         name: string;

package/lib/pkg/index.js

@@ -1,2 +1,2 @@
-import { $ as renderSnapshotYaml, A as parseSettingsDoc, At as parseReposInput, B as planRedaction, Bt as SECRET_TRANSPORT_WITHHELD, C as SNAPSHOT_ONLY_INPUTS, Ct as endpointMethod, D as DEFAULT_SETTINGS_FILE, Dt as SECTION_KEYS, E as parseSnapshotFileConfig, Et as PROBOT_PARITY_KEYS, F as concludeMerge, Ft as VISIBILITY_FILTERS, G as openReportChannel, Gt as prefixedIo, H as toPublicView, Ht as isRateLimitError, I as concludeRun, It as discoverRepos, J as MARKER_LABEL_CONFIG, Jt as resolveCentralTargets, K as ISSUE_TITLE, Kt as redactRanges, L as failRun, Lt as DEFAULT_API_VERSION, M as createVisibilityResolver, Mt as ARCHIVED_FILTERS, N as getRepoFile, Nt as DEFAULT_DISCOVERY_FILTERS, O as resolveTargets, Ot as SettingsFile, P as MERGE_RESULT, Pt as FORKS_FILTERS, Q as parseRecipient, R as PRIVATE_REPOS_POLICIES, Rt as GithubApi, S as SNAPSHOT_INPUTS, St as grantFor, T as parseConfig, Tt as DOCUMENT_DIRECTIVE_KEYS, U as PRIVATE_REPORT_CHANNELS, Ut as collectingIo, V as publicDetail, Vt as isPermissionError, W as applyMarkerInjection, Wt as maskRegistry, X as deliverArtifactReport, Xt as parseRepoSlug, Y as composeReport, Yt as dedupeTargets, Z as encryptReport, _ as INPUT_DECLS, _t as denialPosture, a as snapshotRepositories, at as preflightProbe, b as MERGE_REJECTED_INPUTS, bt as sectionOperations, c as SNAPSHOT_RESULTS, ct as validateSettingsDoc, d as runSnapshot, dt as mergeLayers, et as RERUN_ADVICE, f as runSingle, ft as stripNulls, g as FILTER_INPUTS, gt as sectionModule, h as DEFAULT_PRIVATE_REPOS, ht as allGraphqlOps, i as renderMergedYaml, it as REPO_RESULTS, j as readSettingsFile, jt as AFFILIATIONS, k as runMulti, kt as UNDECLARED_POLICY_SECTIONS, l as SNAPSHOT_SCHEMA_URL, lt as worstOf, m as readLayerFiles, mt as allEndpoints, n as applyRepository, nt as quoteList, o as snapshotRepository, ot as runForRepo, p as foldLayers, pt as SECTIONS, q as MARKER_LABEL, qt as silentIo, r as checkRepository, rt as SectionSelection, s as validateSettings, st as skippedSectionKeys, t as runMerge, tt as describeProblem, u as concludeSnapshot, ut as describeOptOut, v as MERGE_INPUTS, vt as readGating, w as SNAPSHOT_REJECTED_INPUTS, wt as endpointPath, x as MODES, xt as writeGatedReads, y as MERGE_ONLY_INPUTS, yt as sectionGrant, z as capturingIo, zt as SECRET_RESPONSE_WITHHELD } from "./src-BhuD5Ycj.js";
+import { $ as renderSnapshotYaml, A as parseSettingsDoc, At as parseReposInput, B as planRedaction, Bt as SECRET_TRANSPORT_WITHHELD, C as SNAPSHOT_ONLY_INPUTS, Ct as endpointMethod, D as DEFAULT_SETTINGS_FILE, Dt as SECTION_KEYS, E as parseSnapshotFileConfig, Et as PROBOT_PARITY_KEYS, F as concludeMerge, Ft as VISIBILITY_FILTERS, G as openReportChannel, Gt as prefixedIo, H as toPublicView, Ht as isRateLimitError, I as concludeRun, It as discoverRepos, J as MARKER_LABEL_CONFIG, Jt as resolveCentralTargets, K as ISSUE_TITLE, Kt as redactRanges, L as failRun, Lt as DEFAULT_API_VERSION, M as createVisibilityResolver, Mt as ARCHIVED_FILTERS, N as getRepoFile, Nt as DEFAULT_DISCOVERY_FILTERS, O as resolveTargets, Ot as SettingsFile, P as MERGE_RESULT, Pt as FORKS_FILTERS, Q as parseRecipient, R as PRIVATE_REPOS_POLICIES, Rt as GithubApi, S as SNAPSHOT_INPUTS, St as grantFor, T as parseConfig, Tt as DOCUMENT_DIRECTIVE_KEYS, U as PRIVATE_REPORT_CHANNELS, Ut as collectingIo, V as publicDetail, Vt as isPermissionError, W as applyMarkerInjection, Wt as maskRegistry, X as deliverArtifactReport, Xt as parseRepoSlug, Y as composeReport, Yt as dedupeTargets, Z as encryptReport, _ as INPUT_DECLS, _t as denialPosture, a as snapshotRepositories, at as preflightProbe, b as MERGE_REJECTED_INPUTS, bt as sectionOperations, c as SNAPSHOT_RESULTS, ct as validateSettingsDoc, d as runSnapshot, dt as mergeLayers, et as RERUN_ADVICE, f as runSingle, ft as stripNulls, g as FILTER_INPUTS, gt as sectionModule, h as DEFAULT_PRIVATE_REPOS, ht as allGraphqlOps, i as renderMergedYaml, it as REPO_RESULTS, j as readSettingsFile, jt as AFFILIATIONS, k as runMulti, kt as UNDECLARED_POLICY_SECTIONS, l as SNAPSHOT_SCHEMA_URL, lt as worstOf, m as readLayerFiles, mt as allEndpoints, n as applyRepository, nt as quoteList, o as snapshotRepository, ot as runForRepo, p as foldLayers, pt as SECTIONS, q as MARKER_LABEL, qt as silentIo, r as checkRepository, rt as SectionSelection, s as validateSettings, st as skippedSectionKeys, t as runMerge, tt as describeProblem, u as concludeSnapshot, ut as describeOptOut, v as MERGE_INPUTS, vt as readGating, w as SNAPSHOT_REJECTED_INPUTS, wt as endpointPath, x as MODES, xt as writeGatedReads, y as MERGE_ONLY_INPUTS, yt as sectionGrant, z as capturingIo, zt as SECRET_RESPONSE_WITHHELD } from "./src-B13lb6Pp.js";
 export { AFFILIATIONS, ARCHIVED_FILTERS, DEFAULT_API_VERSION, DEFAULT_DISCOVERY_FILTERS, DEFAULT_PRIVATE_REPOS, DEFAULT_SETTINGS_FILE, DOCUMENT_DIRECTIVE_KEYS, FILTER_INPUTS, FORKS_FILTERS, GithubApi, INPUT_DECLS, ISSUE_TITLE, MARKER_LABEL, MARKER_LABEL_CONFIG, MERGE_INPUTS, MERGE_ONLY_INPUTS, MERGE_REJECTED_INPUTS, MERGE_RESULT, MODES, PRIVATE_REPORT_CHANNELS, PRIVATE_REPOS_POLICIES, PROBOT_PARITY_KEYS, REPO_RESULTS, RERUN_ADVICE, SECRET_RESPONSE_WITHHELD, SECRET_TRANSPORT_WITHHELD, SECTIONS, SECTION_KEYS, SNAPSHOT_INPUTS, SNAPSHOT_ONLY_INPUTS, SNAPSHOT_REJECTED_INPUTS, SNAPSHOT_RESULTS, SNAPSHOT_SCHEMA_URL, SectionSelection, SettingsFile, UNDECLARED_POLICY_SECTIONS, VISIBILITY_FILTERS, allEndpoints, allGraphqlOps, applyMarkerInjection, applyRepository, capturingIo, checkRepository, collectingIo, composeReport, concludeMerge, concludeRun, concludeSnapshot, createVisibilityResolver, dedupeTargets, deliverArtifactReport, denialPosture, describeOptOut, describeProblem, discoverRepos, encryptReport, endpointMethod, endpointPath, failRun, foldLayers, getRepoFile, grantFor, isPermissionError, isRateLimitError, maskRegistry, mergeLayers, openReportChannel, parseConfig, parseRecipient, parseRepoSlug, parseReposInput, parseSettingsDoc, parseSnapshotFileConfig, planRedaction, prefixedIo, preflightProbe, publicDetail, quoteList, readGating, readLayerFiles, readSettingsFile, redactRanges, renderMergedYaml, renderSnapshotYaml, resolveCentralTargets, resolveTargets, runForRepo, runMerge, runMulti, runSingle, runSnapshot, sectionGrant, sectionModule, sectionOperations, silentIo, skippedSectionKeys, snapshotRepositories, snapshotRepository, stripNulls, toPublicView, validateSettings, validateSettingsDoc, worstOf, writeGatedReads };

package/lib/pkg/{src-BhuD5Ycj.js → src-B13lb6Pp.js}

@@ -4192,16 +4192,11 @@ const WILDCARD_KEYS = [
 	"required_deployments"
 ];
 const WILDCARD_KEY_SET = new Set(WILDCARD_KEYS);
-const GRAPHQL = {
-	rulesQuery: graphqlOp()({
-		name: "BranchProtectionRules",
-		kind: "read",
-		connection: { path: ["repository", "branchProtectionRules"] },
-		outcomes: {
-			ok: "the repository's classic branch protection rules",
-			NOT_FOUND: "the repository is not visible to the token; read as no rules"
-		},
-		query: `query BranchProtectionRules($owner: String!, $repo: String!, $cursor: String) {
+/**
+* The rule selection both rules reads share, so the snapshot's read cannot lag the planner's
+* translation tables (test/sections/graphql-queries.test.ts asserts every twin is selected).
+*/
+const RULES_SELECTION = `($owner: String!, $repo: String!, $cursor: String) {
   repository(owner: $owner, name: $repo) {
     branchProtectionRules(first: 100, after: $cursor) {
       nodes {
@@ -4241,7 +4236,24 @@ const GRAPHQL = {
       pageInfo { hasNextPage endCursor }
     }
   }
-}`
+}`;
+const GRAPHQL = {
+	rulesQuery: graphqlOp()({
+		name: "BranchProtectionRules",
+		kind: "read",
+		connection: { path: ["repository", "branchProtectionRules"] },
+		outcomes: {
+			ok: "the repository's classic branch protection rules",
+			NOT_FOUND: "the repository is not visible to the token; read as no rules"
+		},
+		query: `query BranchProtectionRules${RULES_SELECTION}`
+	}),
+	rulesSnapshot: graphqlOp()({
+		name: "BranchProtectionRulesSnapshot",
+		kind: "read",
+		connection: { path: ["repository", "branchProtectionRules"] },
+		outcomes: { ok: "the repository's classic branch protection rules, for the snapshot" },
+		query: `query BranchProtectionRulesSnapshot${RULES_SELECTION}`
 	}),
 	repoLookup: graphqlOp()({
 		name: "BranchProtectionRepository",
@@ -4325,8 +4337,17 @@ function hasRoutedGraphqlKeys(protection) {
 async function fetchRules(ctx) {
 	const read = await ctx.read.rulesQuery.listConnection(repoVariables(ctx));
 	if ("error" in read) return null;
+	return indexRules(read.items);
+}
+/** The snapshot's read: the op tolerates no outcome, so a denial throws with the grant advice. */
+async function fetchRulesForSnapshot(ctx) {
+	const read = await ctx.read.rulesSnapshot.listConnection(repoVariables(ctx));
+	if ("error" in read) throw new Error("BUG: branches: the snapshot rules query declares no tolerated outcome, yet its read returned an error instead of throwing");
+	return indexRules(read.items);
+}
+function indexRules(items) {
 	const byPattern = /* @__PURE__ */ new Map();
-	for (const node of read.items) if (typeof node === "object" && node !== null) {
+	for (const node of items) if (typeof node === "object" && node !== null) {
 		const rule = node;
 		if (rule.bypassForcePushAllowances?.pageInfo?.hasNextPage === true) throw new Error(`branches: the live protection rule "${String(rule.pattern)}" allows more than 100 force-push bypass actors, which this section cannot read back completely; trim the live allowance list below 100 to manage it here`);
 		byPattern.set(String(rule.pattern), rule);
@@ -4367,6 +4388,32 @@ function classicViewOfRule(node) {
 	out.required_deployments = node.requiresDeployments === true ? { environments: Array.isArray(node.requiredDeploymentEnvironments) ? node.requiredDeploymentEnvironments : [] } : null;
 	return out;
 }
+/**
+* The two routed keys of a LITERAL entry as the snapshot declares them: only a non-empty allowance
+* list and a requirement that is on. An omitted routed key leaves the live value untouched (unlike
+* the replacing PUT, which resets an omitted control), so the file pins what is set.
+*/
+function routedKeysSnapshot(node) {
+	const view = classicViewOfRule(node);
+	const out = {};
+	const actors = view.force_push_bypassers;
+	if (actors.length > 0) out.force_push_bypassers = actors;
+	if (view.required_deployments !== null) out.required_deployments = view.required_deployments;
+	return out;
+}
+/**
+* A WILDCARD rule as the snapshot declares it: the classic view with every control that is off
+* dropped and a nested null (an unset review count) omitted, so the entry carries only keys the
+* wildcard shape accepts and the check reads clean against the same rule.
+*/
+function wildcardSnapshot(node) {
+	const out = {};
+	for (const [key, value] of Object.entries(classicViewOfRule(node))) {
+		if (value === false || value === null || Array.isArray(value) && value.length === 0) continue;
+		out[key] = typeof value === "object" && !Array.isArray(value) ? Object.fromEntries(Object.entries(value).filter(([, inner]) => inner !== null)) : value;
+	}
+	return out;
+}
 /** Shape validation already restricted a wildcard entry's keys, so an unknown key here is a bug. */
 function translateWildcardProtection(protection) {
 	const input = {};
@@ -4696,8 +4743,14 @@ const permission$13 = { repo: ["administration"] };
 const LiveProtection = z.looseObject({ required_signatures: z.looseObject({ enabled: z.boolean() }).optional() });
 /** One item of the protected-branch listing; only the name is read (the protection is probed). */
 const LiveBranchSummary = z.looseObject({ name: z.string() });
-/** The snapshot note for the surface the REST reads cannot carry. */
-const GRAPHQL_ONLY_NOTE = "protection.force_push_bypassers, protection.required_deployments, and wildcard rules ride the GraphQL rule surface, which snapshot does not read; an omitted key leaves its live value untouched, so declare them to manage them. A branch a wildcard rule protects is written here as a LITERAL entry carrying that rule's protection (the REST reads name no pattern), and applying it would create a literal rule beside the wildcard; replace such entries with one wildcard entry naming the pattern";
+/**
+* A literal-pattern rule the REST reads did not surface as a protected branch: no branch of that
+* name exists (a pattern needs none), or its protection probe was denied. A literal entry applies
+* through the REST PUT, which needs the branch, so the rule is noted instead of written. The
+* pattern appears once and the text stays short, so the rendered header line ("# " prefixed)
+* stays under 256 chars for patterns up to 54 chars.
+*/
+const unreachableLiteralRuleNote = (pattern) => `branches[${pattern}]: rule kept out of the snapshot: REST read no protected branch by this name (the branch is missing, or its protection is unreadable); create the branch or fix the grant, then snapshot again`;
 const WILDCARD_KEY_ERROR = (name, key) => `the wildcard entry "${name}" declares protection.${key}, which this section does not manage on wildcard rules; only the keys it can round-trip through the GraphQL rule mutations apply here: [${WILDCARD_KEYS.join(", ")}]. For actor lists and richer controls, prefer the rulesets section (the modern successor of classic protection)`;
 const branchesSection = {
 	key: "branches",
@@ -4798,23 +4851,36 @@ const branchesSection = {
 	},
 	async snapshot(ctx) {
 		const listed = parseLive(this, ENDPOINTS$15.listProtected, z.array(LiveBranchSummary), await ctx.read.listProtected.listAll({ query: { protected: "true" } }));
+		const rules = await fetchRulesForSnapshot(ctx);
 		const entries = [];
+		const notes = [];
 		for (const { name } of listed) {
 			const probe = await ctx.read.getProtection.probeAbsent({ params: { branch: name } });
 			if ("missing" in probe) continue;
+			const rule = rules.get(name);
+			if (rule === void 0) continue;
 			const live = parseLive(this, ENDPOINTS$15.getProtection, LiveProtection, probe.data, `branch "${name}"`);
 			entries.push({
 				name,
-				protection: protectionSnapshot(live)
+				protection: {
+					...protectionSnapshot(live),
+					...routedKeysSnapshot(rule)
+				}
 			});
 		}
+		const written = new Set(entries.map((entry) => entry.name));
+		for (const [pattern, rule] of rules) if (isWildcardPattern(pattern)) entries.push({
+			name: pattern,
+			protection: wildcardSnapshot(rule)
+		});
+		else if (!written.has(pattern)) notes.push(unreachableLiteralRuleNote(pattern));
 		if (entries.length === 0) return {
 			value: void 0,
-			notes: []
+			notes
 		};
 		return {
 			value: entries,
-			notes: [GRAPHQL_ONLY_NOTE]
+			notes
 		};
 	}
 };
@@ -6333,17 +6399,32 @@ async function planEnvironmentSecrets(ctx, section, envName, policy, entries, li
 	}
 	return planned;
 }
+//#endregion
+//#region src/sections/environments/pins.ts
+/**
+* Pinned environments (the routed `pinned` scalar): the GraphQL operations and the pin/unpin/reorder
+* planning. plan() gates the call on a declared `pinned` key, so a pin-free file never touches /graphql.
+*/
+/** The pins selection both pins reads share, so the snapshot's read cannot lag the planner's. */
+const PINS_SELECTION = "($owner: String!, $repo: String!, $cursor: String) { repository(owner: $owner, name: $repo) { pinnedEnvironments(first: 100, after: $cursor) { nodes { position environment { name } } pageInfo { hasNextPage endCursor } } } }";
 const GRAPHQL_OPS$1 = {
 	pins: graphqlOp()({
 		name: "EnvironmentPins",
 		kind: "read",
-		query: "query EnvironmentPins($owner: String!, $repo: String!, $cursor: String) { repository(owner: $owner, name: $repo) { pinnedEnvironments(first: 100, after: $cursor) { nodes { position environment { name } } pageInfo { hasNextPage endCursor } } } }",
+		query: `query EnvironmentPins${PINS_SELECTION}`,
 		connection: { path: ["repository", "pinnedEnvironments"] },
 		outcomes: {
 			ok: "the pinned environments with their 1-based positions",
 			NOT_FOUND: "the repository is not visible to the token; read as no pins (the denial surfaces on the first pin write)"
 		}
 	}),
+	pinsSnapshot: graphqlOp()({
+		name: "EnvironmentPinsSnapshot",
+		kind: "read",
+		query: `query EnvironmentPinsSnapshot${PINS_SELECTION}`,
+		connection: { path: ["repository", "pinnedEnvironments"] },
+		outcomes: { ok: "the pinned environments with their 1-based positions, for the snapshot" }
+	}),
 	pin: graphqlOp()({
 		name: "PinEnvironment",
 		kind: "write",
@@ -6382,7 +6463,16 @@ function livePin(node) {
 async function listLivePins(ctx) {
 	const listed = await ctx.read.pins.listConnection(repoVariables(ctx));
 	if ("error" in listed) return [];
-	return listed.items.map(livePin).sort((a, b) => a.position - b.position);
+	return rankPins(listed.items);
+}
+/** The snapshot's read: the op tolerates no outcome, so a denial throws with the grant advice. */
+async function snapshotPins(ctx) {
+	const listed = await ctx.read.pinsSnapshot.listConnection(repoVariables(ctx));
+	if ("error" in listed) throw new Error("BUG: environments: the snapshot pins query declares no tolerated outcome, yet its read returned an error instead of throwing");
+	return rankPins(listed.items).map((pin) => pin.name);
+}
+function rankPins(nodes) {
+	return nodes.map(livePin).sort((a, b) => a.position - b.position);
 }
 /** Environment names are case-insensitive on GitHub. */
 function pinKey(name) {
@@ -6513,9 +6603,41 @@ async function planPinned(ctx, declarations) {
 /**
 * The snapshot half of the nested seam: one environment's sub-resource lists read back in their
 * declared wrapped form, each under its planner's own default policy (nestedDefaultPolicy), and
-* the environment-level GraphQL surface the REST reads cannot carry, as a note.
+* the pin state read off the GraphQL pins connection folded onto the entries.
+*/
+/**
+* The pin state folded onto the entries: the pinned environments lead, in rank order, each with
+* `pinned: true` (the planner reads declaration order as pin order, so any other order would plan
+* a reorder); the rest follow in listing order without the key, since an unpinned environment has
+* nothing to declare and an absent key leaves a pin untouched. A pin naming no listed environment
+* (matched case-insensitively, as GitHub names them) cannot be declared, and the declared pins
+* must lead the live list, so from that rank on no pin is declared; one note names them all.
 */
-const PINNED_NOTE = "pinned rides the GraphQL pins connection, which snapshot does not read; an entry without the key leaves its pin untouched, so declare pinned to manage pins";
+function withPins(entries, pins) {
+	const byKey = new Map(entries.map((entry) => [entry.name.toLowerCase(), entry]));
+	const leading = [];
+	const notes = [];
+	const unlistedAt = pins.findIndex((name) => !byKey.has(name.toLowerCase()));
+	const declared = unlistedAt < 0 ? pins : pins.slice(0, unlistedAt);
+	for (const name of declared) {
+		const entry = byKey.get(name.toLowerCase());
+		byKey.delete(name.toLowerCase());
+		const { name: entryName, ...rest } = entry;
+		leading.push({
+			name: entryName,
+			pinned: true,
+			...rest
+		});
+	}
+	if (unlistedAt >= 0) {
+		const undeclared = pins.slice(unlistedAt + 1).map((name) => `"${name}"`);
+		notes.push(`environments: the pinned environment "${pins[unlistedAt]}" is not in the environment listing, so its pin cannot be declared` + (undeclared.length === 0 ? "" : `; the pins ranked after it (${undeclared.join(", ")}) are left without the pinned key too, since declared pins must lead the live list`));
+	}
+	return {
+		entries: [...leading, ...byKey.values()],
+		notes
+	};
+}
 function wrapped(key, entries) {
 	return {
 		_undeclared: nestedDefaultPolicy(key),
@@ -6684,9 +6806,10 @@ const environmentsSection = {
 			});
 			notes.push(...nestedNotes);
 		}
-		notes.push(...sharedSecretNotes(entries), PINNED_NOTE);
+		const pinned = withPins(entries, await snapshotPins(ctx));
+		notes.push(...pinned.notes, ...sharedSecretNotes(pinned.entries));
 		return {
-			value: entries,
+			value: pinned.entries,
 			notes
 		};
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vivswan/github-settings-as-code",
-  "version": "2.0.1-main.1090.g15ef0c9",
+  "version": "2.0.1-main.1110.g63435fc",
   "description": "GitHub Action applying declarative repository settings: rulesets, labels, branch protection, and more.",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",