@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/_lib/forge_protection.ts

@@ -0,0 +1,381 @@
+/**
+ * The five `forge_protection` rows, read from the forge rather than guessed.
+ *
+ * `road-to-adversarial-verification-and-long-runs` Phase 3.2. ADR-268 § 3 trades
+ * the owner's confirmation for a mechanical check, and branch protection is the
+ * check it trades for — so a run that cannot say whether protection exists has
+ * not established the thing the trade depends on.
+ *
+ * **Every row carries the API call its value came from, and a row that was not
+ * read says so.** That is the whole shape: the step's word is *read, never
+ * guessed*, and the only way a reader can tell one from the other is if the
+ * provenance travels with the value. A row is `satisfied` / `unsatisfied` only
+ * when a named call produced it; otherwise it is `unread`, which is a third
+ * state and never a false.
+ *
+ * **Rulesets, not the classic branch-protection endpoint.** On this repository
+ * `repos/<owner>/<repo>/branches/main/protection` returns `404 {"message":"Branch
+ * not protected"}` while an active ruleset protects the default branch — so a
+ * checker reading the classic endpoint reports "unprotected" for a repository
+ * that is protected. The `forge-protection-settings` blocker was re-scoped for
+ * exactly this reason on 2026-09-10, and the re-scope forbids treating that 404
+ * as absence of protection. No ruleset ID is pinned: rulesets can be replaced or
+ * split, and pinning one would break on the first change.
+ *
+ * Pure. The network lives in the caller, so both polarities are testable offline.
+ */
+
+import type { BypassActor, RulesetDetail } from './platform_anchor.js';
+
+/** Whether a row was established, refuted, or never read. */
+export type RowState = 'satisfied' | 'unsatisfied' | 'unread';
+
+/** One `forge_protection` row. */
+export interface ProtectionRow {
+    /** Stable key. Rows are addressed by this, never by position. */
+    readonly id: string;
+    readonly state: RowState;
+    /**
+     * The forge API call this value came from — or would come from, when the row
+     * is `unread`. Never empty: a value whose provenance is unstated is the
+     * guess this block exists to refuse.
+     */
+    readonly source: string;
+    /** One line a human can act on when the row is not satisfied. */
+    readonly detail: string;
+}
+
+/** The five rows, in the order the blocker's own table lists them. */
+export const PROTECTION_ROW_IDS: readonly string[] = [
+    'default_branch_protected',
+    'required_checks_present',
+    'force_push_disabled',
+    'auto_merge_available',
+    'deploy_via_pipeline_only',
+] as const;
+
+/** What a caller must supply for a row to be readable. `null` = not read. */
+export interface ForgeReading {
+    /** `repos/<repo>/rulesets` + `/rulesets/<id>`, or `null` when unread. */
+    readonly rulesets: readonly RulesetDetail[] | null;
+    /** The repository's default branch, or `null` when unread. */
+    readonly defaultBranch: string | null;
+    /** `repos/<repo>` → `allow_auto_merge`, or `null` when unread. */
+    readonly allowAutoMerge: boolean | null;
+    /**
+     * `repos/<repo>/environments` → whether every environment with deployment
+     * branch policies restricts them, or `null` when unread.
+     *
+     * Deliberately a boolean the caller derives rather than a raw payload: what
+     * the row asserts is a property of the SET of environments, and handing this
+     * module the raw list would put that judgement in two places.
+     */
+    readonly deployRestricted: boolean | null;
+}
+
+/**
+ * The all-null reading: nothing was queried.
+ *
+ * Lives here, beside {@link ForgeReading}, rather than in the `doctor` caller
+ * that first needed it — `_lib/forge_reader.ts` returns it on every failure
+ * path, and a second hand-written all-null literal is exactly the drift that
+ * makes "offline output is unchanged" an assertion instead of a fact.
+ *
+ * It MOVED from `_cli/doctor_execution.ts`, which no longer exports it in any
+ * form. Nothing broke, because nothing outside that file imported it — but an
+ * earlier draft of this comment claimed a re-export kept every caller in place,
+ * and no such shim was ever written. Corrected rather than quietly deleted: a
+ * comment describing a compatibility layer that does not exist is the next
+ * reader's false premise.
+ */
+export const UNREAD_FORGE: ForgeReading = {
+    rulesets: null,
+    defaultBranch: null,
+    allowAutoMerge: null,
+    deployRestricted: null,
+};
+
+/**
+ * The two fields of an environment this row reads, as
+ * `GET repos/{owner}/{repo}/environments` returns them.
+ *
+ * A NARROW PROJECTION, not the full payload: the real response also carries
+ * `id`, `protection_rules`, `can_admins_bypass`, timestamps and more. Declared
+ * this way on purpose — a caller passes the real object and structural typing
+ * accepts the superset, while the interface states exactly which fields this
+ * decision depends on. Calling it "the shape" would overstate it.
+ *
+ * `null` is GitHub's encoding for *no restriction at all* — every branch may
+ * deploy. It is therefore the one shape that refutes the row.
+ */
+export interface EnvironmentPolicy {
+    readonly name: string;
+    readonly deployment_branch_policy: {
+        readonly protected_branches?: boolean;
+        readonly custom_branch_policies?: boolean;
+    } | null;
+}
+
+/**
+ * Derive `deployRestricted` from the environments payload.
+ *
+ * **Both restriction mechanisms count, and reading only one is the defect this
+ * function exists to close.** GitHub restricts deployment branches two ways:
+ * `protected_branches` (whatever the forge currently treats as protected) and
+ * `custom_branch_policies` (an explicit named list). A checker that reads only
+ * the first reports "accepts a deployment from any branch" for an environment
+ * pinned to exactly one named branch — which is the opposite of what the
+ * payload says, and is precisely the misreading recorded against this
+ * repository on 2026-09-13: `github-pages` carried
+ * `custom_branch_policies: true` with a single policy, `main`, and was written
+ * up as unrestricted because only `protected_branches` was consulted.
+ *
+ * The named-list mechanism is also the STRICTER of the two here, which is why
+ * the row is satisfied without changing the forge: `protected_branches` widens
+ * with the protected set, while a custom list names one branch and stays there.
+ * On a ruleset-protected repository it is additionally the safer mechanism —
+ * `protected_branches` resolves against a notion of protection whose classic
+ * endpoint 404s here (see the module header), so switching to it would trade a
+ * precise restriction for one whose evaluation is exactly the ambiguity the
+ * `forge-protection-settings` re-scope forbids relying on.
+ *
+ * **An empty environment set returns `null`, not `true`.** The first draft
+ * returned `true` on the reasoning that with no environment there is no
+ * deployment surface to leave open. That is sound about a *confirmed* empty
+ * set and wrong about the value actually reaching this function: an empty
+ * array is what a failed fetch, a truncated page, or a caller that never
+ * queried also produces, and collapsing those into `satisfied` is exactly the
+ * quiet false-positive the three-state row exists to prevent. `null` maps to
+ * `unread`, which is the state this module already reserves for a value nobody
+ * established. A caller that has genuinely confirmed zero environments can say
+ * so by passing `true` itself; it cannot be inferred from the array alone.
+ *
+ * **Wildcard patterns.** A custom policy's NAMES live behind a second call
+ * (`GET .../environments/{name}/deployment-branch-policies`) and accept globs,
+ * so `custom_branch_policies: true` alone cannot distinguish a policy pinned to
+ * `main` from one whose pattern is `*`. Pass `patternsByEnv` when those names
+ * have been read: an environment whose patterns admit everything is reported
+ * unrestricted. Omit it and the flag is trusted — the narrower guarantee was
+ * not checked, which is stated here rather than left for a reader to discover.
+ *
+ * **A confirmed-EMPTY pattern list also yields `false`, and it is NOT the same
+ * case as a wildcard.** With `custom_branch_policies: true` and zero named
+ * patterns nothing matches, so nothing can deploy — strictly the most
+ * restrictive posture there is, and the exact opposite of `*`. Both land on
+ * `false` deliberately, because this row feeds an ACTION line rather than a
+ * permission: an environment configured to accept no deployment at all is a
+ * misconfiguration worth a human look, and `false` surfaces it where `true`
+ * would silently bless it. The direction is the safe one — it can under-report
+ * satisfaction, never over-report it. Written down because the two states are
+ * genuinely opposite, and a reader deriving the behaviour from the expression
+ * alone would reasonably take it for a bug.
+ */
+export function deployRestrictedFrom(
+    environments: readonly EnvironmentPolicy[],
+    patternsByEnv?: Readonly<Record<string, readonly string[]>>,
+): boolean | null {
+    if (environments.length === 0) return null;
+    return environments.every((env) => {
+        const policy = env.deployment_branch_policy;
+        if (policy === null || policy === undefined) return false;
+        if (policy.protected_branches === true) return true;
+        if (policy.custom_branch_policies !== true) return false;
+        const patterns = patternsByEnv?.[env.name];
+        if (patterns === undefined) return true;
+        // A policy admitting every ref restricts nothing, whatever the flag says.
+        return patterns.length > 0 && !patterns.some((p) => p === '*' || p === '**');
+    });
+}
+
+const SOURCE = {
+    rulesets: 'GET repos/{owner}/{repo}/rulesets + GET .../rulesets/{id}',
+    repo: 'GET repos/{owner}/{repo} (allow_auto_merge)',
+    environments: 'GET repos/{owner}/{repo}/environments (deployment_branch_policy)',
+} as const;
+
+/** `true` when this ruleset is active and targets branches. */
+function isActiveBranchRuleset(rs: RulesetDetail): boolean {
+    return rs.enforcement === 'active' && rs.target === 'branch';
+}
+
+/** `true` when the ruleset's ref conditions reach the default branch. */
+function reachesDefaultBranch(rs: RulesetDetail, defaultBranch: string): boolean {
+    const include = rs.conditions?.ref_name?.include ?? [];
+    return include.some(
+        (p) => p === '~DEFAULT_BRANCH' || p === '~ALL' || p === `refs/heads/${defaultBranch}`,
+    );
+}
+
+function hasRule(rs: RulesetDetail, type: string): boolean {
+    return (rs.rules ?? []).some((r) => r.type === type);
+}
+
+function requiredContexts(rs: RulesetDetail): string[] {
+    for (const r of rs.rules ?? []) {
+        if (r.type !== 'required_status_checks') continue;
+        const p = r.parameters;
+        if (p === null || typeof p !== 'object') continue;
+        const list = (p as Record<string, unknown>)['required_status_checks'];
+        if (!Array.isArray(list)) continue;
+        return list
+            .map((e) =>
+                e !== null && typeof e === 'object'
+                    ? (e as Record<string, unknown>)['context']
+                    : null,
+            )
+            .filter((c): c is string => typeof c === 'string');
+    }
+    return [];
+}
+
+/**
+ * Map a forge reading onto the five rows.
+ *
+ * Never throws and never invents: an input of `null` produces `unread`, which is
+ * why the return type has three states rather than two. A gate that reports
+ * `false` for something it did not look at is the failure this separation exists
+ * to prevent — and it is the failure the `forge-protection-settings` re-scope
+ * names, one layer up.
+ */
+export function forgeProtectionRows(reading: ForgeReading): ProtectionRow[] {
+    const rows: ProtectionRow[] = [];
+    const rulesets = reading.rulesets;
+    const branch = reading.defaultBranch;
+
+    const covering =
+        rulesets === null || branch === null
+            ? null
+            : rulesets.filter((rs) => isActiveBranchRuleset(rs) && reachesDefaultBranch(rs, branch));
+
+    rows.push(
+        covering === null
+            ? {
+                  id: 'default_branch_protected',
+                  state: 'unread',
+                  source: SOURCE.rulesets,
+                  detail: 'the rulesets were not queried',
+              }
+            : covering.length > 0
+              ? {
+                    id: 'default_branch_protected',
+                    state: 'satisfied',
+                    source: SOURCE.rulesets,
+                    detail: `${String(covering.length)} active branch ruleset(s) cover the default branch`,
+                }
+              : {
+                    id: 'default_branch_protected',
+                    state: 'unsatisfied',
+                    source: SOURCE.rulesets,
+                    detail:
+                        'no active branch ruleset covers the default branch. NOTE: the classic ' +
+                        'branches/<b>/protection endpoint 404s on a ruleset-protected repository, ' +
+                        'so a 404 there is not evidence for this row.',
+                },
+    );
+
+    const contexts = covering === null ? null : covering.flatMap(requiredContexts);
+    rows.push(
+        contexts === null
+            ? {
+                  id: 'required_checks_present',
+                  state: 'unread',
+                  source: SOURCE.rulesets,
+                  detail: 'the rulesets were not queried',
+              }
+            : contexts.length > 0
+              ? {
+                    id: 'required_checks_present',
+                    state: 'satisfied',
+                    source: SOURCE.rulesets,
+                    detail: `${String(contexts.length)} required context(s): ${contexts.join(', ')}`,
+                }
+              : {
+                    id: 'required_checks_present',
+                    state: 'unsatisfied',
+                    source: SOURCE.rulesets,
+                    detail: 'no required status check context is configured',
+                },
+    );
+
+    const noFastForward = covering === null ? null : covering.some((rs) => hasRule(rs, 'non_fast_forward'));
+    rows.push(
+        noFastForward === null
+            ? {
+                  id: 'force_push_disabled',
+                  state: 'unread',
+                  source: SOURCE.rulesets,
+                  detail: 'the rulesets were not queried',
+              }
+            : {
+                  id: 'force_push_disabled',
+                  state: noFastForward ? 'satisfied' : 'unsatisfied',
+                  source: SOURCE.rulesets,
+                  detail: noFastForward
+                      ? 'a non_fast_forward rule is active on the default branch'
+                      : 'no non_fast_forward rule covers the default branch',
+              },
+    );
+
+    rows.push(
+        reading.allowAutoMerge === null
+            ? {
+                  id: 'auto_merge_available',
+                  state: 'unread',
+                  source: SOURCE.repo,
+                  detail: 'the repository record was not queried',
+              }
+            : {
+                  id: 'auto_merge_available',
+                  state: reading.allowAutoMerge ? 'satisfied' : 'unsatisfied',
+                  source: SOURCE.repo,
+                  detail: reading.allowAutoMerge
+                      ? 'allow_auto_merge is enabled'
+                      : 'allow_auto_merge is disabled — merge delivery cannot queue behind checks',
+              },
+    );
+
+    rows.push(
+        reading.deployRestricted === null
+            ? {
+                  id: 'deploy_via_pipeline_only',
+                  state: 'unread',
+                  source: SOURCE.environments,
+                  detail: 'the environments were not queried',
+              }
+            : {
+                  id: 'deploy_via_pipeline_only',
+                  state: reading.deployRestricted ? 'satisfied' : 'unsatisfied',
+                  source: SOURCE.environments,
+                  detail: reading.deployRestricted
+                      ? 'every environment restricts its deployment branches'
+                      : 'at least one environment accepts a deployment from any branch',
+              },
+    );
+
+    return rows;
+}
+
+/**
+ * The human ACTION lines for rows that are not satisfied.
+ *
+ * **Not a halt, and the step says so explicitly**: `doctor` LISTS what is
+ * missing and the run continues. An `unread` row produces an action too — "go
+ * and read it" is a real instruction, and silently omitting it would make an
+ * unmeasured row indistinguishable from a satisfied one, which is the same
+ * conflation the three-state row type exists to prevent.
+ */
+export function protectionActions(rows: readonly ProtectionRow[]): string[] {
+    return rows
+        .filter((r) => r.state !== 'satisfied')
+        .map((r) => `${r.id}: ${r.state} — ${r.detail} (source: ${r.source})`);
+}
+
+/** Unconditional bypass actors across the covering rulesets, for reporting. */
+export function unconditionalBypasses(
+    rulesets: readonly RulesetDetail[],
+    defaultBranch: string,
+): BypassActor[] {
+    return rulesets
+        .filter((rs) => isActiveBranchRuleset(rs) && reachesDefaultBranch(rs, defaultBranch))
+        .flatMap((rs) => (rs.bypass_actors ?? []).filter((a) => a.bypass_mode === 'always'));
+}