mesh-catalog/modules/gitea/protectfull.ts

// Every field of a branch protection rule, set through one tool (gitea_branch_protection_set_full; the operator,
// 2026-10-28: "just make a generic tool so you can setup any configuration"). Pure, so it is tested without a forge:
// which fields the forge's rule takes and of what kind, the body a call sends, and whether the rule the forge then
// applies to the branch is one the controller registers a module from (judgedRule, mesh-control
// cmd/mesh-controller/build_source.go).

import { TOOLS_ACCOUNT } from "./tools-account.js";
import type { BranchProtection } from "./protection.js";

type Kind = "boolean" | "logins" | "strings" | "number" | "string";

/** Every field gitea's branch protection API takes (CreateBranchProtectionOption / EditBranchProtectionOption), by its
 *  own name, and its kind. A call names them as the forge does; rule_name is the branch argument, never a field. */
export const PROTECTION_FIELDS: Record<string, { kind: Kind; says: string }> = {
  enable_push: { kind: "boolean", says: "whether anyone who writes may push to the branch directly (false: no direct push)" },
  enable_push_whitelist: { kind: "boolean", says: "with enable_push, only the push whitelist may push" },
  push_whitelist_usernames: { kind: "logins", says: "the logins that may push directly" },
  push_whitelist_teams: { kind: "strings", says: "the teams that may push directly" },
  push_whitelist_deploy_keys: { kind: "boolean", says: "whether deploy keys may push" },
  enable_force_push: { kind: "boolean", says: "whether a force push is taken" },
  enable_force_push_allowlist: { kind: "boolean", says: "with enable_force_push, only the force-push allowlist may" },
  force_push_allowlist_usernames: { kind: "logins", says: "the logins that may force-push" },
  force_push_allowlist_teams: { kind: "strings", says: "the teams that may force-push" },
  force_push_allowlist_deploy_keys: { kind: "boolean", says: "whether deploy keys may force-push" },
  enable_merge_whitelist: { kind: "boolean", says: "whether only the merge whitelist may merge" },
  merge_whitelist_usernames: { kind: "logins", says: "the logins that may merge (the controller's trunk rule wants mesh-tools, no agent-<node>)" },
  merge_whitelist_teams: { kind: "strings", says: "the teams that may merge" },
  enable_status_check: { kind: "boolean", says: "whether the statuses in status_check_contexts must pass to merge" },
  status_check_contexts: { kind: "strings", says: "the required commit statuses, e.g. mesh/check" },
  required_approvals: { kind: "number", says: "how many approving reviews a merge needs" },
  enable_approvals_whitelist: { kind: "boolean", says: "whether only the approvals whitelist's reviews count" },
  approvals_whitelist_username: { kind: "logins", says: "the logins whose approvals count" },
  approvals_whitelist_teams: { kind: "strings", says: "the teams whose approvals count" },
  block_on_rejected_reviews: { kind: "boolean", says: "a review asking changes blocks the merge" },
  block_on_official_review_requests: { kind: "boolean", says: "an open official review request blocks the merge" },
  block_on_outdated_branch: { kind: "boolean", says: "a head behind the branch blocks the merge" },
  dismiss_stale_approvals: { kind: "boolean", says: "a new commit dismisses earlier approvals" },
  ignore_stale_approvals: { kind: "boolean", says: "approvals of an earlier commit do not count" },
  require_signed_commits: { kind: "boolean", says: "every commit must be signed" },
  protected_file_patterns: { kind: "string", says: "files no push may change, ';'-separated globs" },
  unprotected_file_patterns: { kind: "string", says: "files a push may change even without push rights, ';'-separated globs" },
  block_admin_merge_override: { kind: "boolean", says: "true: an administrator cannot merge past the rule (the controller's trunk rule wants true)" },
  priority: { kind: "number", says: "the rule's order among glob rules" },
};

/** A forge login. */
const LOGIN = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,39}$/;

/** The forge body for the fields given: each checked against its kind, a field not given left out (the forge keeps it on
 *  an edit), an unknown field refused before anything is sent. Throws on the first wrong field. */
export function fullProtectionBody(args: Record<string, unknown>, given: string[]): Record<string, unknown> {
  const body: Record<string, unknown> = {};
  for (const name of given) {
    const field = PROTECTION_FIELDS[name];
    if (!field) throw new Error(`${name} is no field of a branch protection rule; the fields are ${Object.keys(PROTECTION_FIELDS).join(", ")}`);
    const v = args[name];
    switch (field.kind) {
      case "boolean":
        if (typeof v !== "boolean") throw new Error(`${name} is true or false`);
        body[name] = v;
        break;
      case "number":
        if (typeof v !== "number" || !Number.isInteger(v) || v < 0) throw new Error(`${name} is a whole number, 0 or more`);
        body[name] = v;
        break;
      case "string":
        if (typeof v !== "string") throw new Error(`${name} is a string`);
        body[name] = v;
        break;
      case "strings":
      case "logins": {
        if (!Array.isArray(v) || v.some((s) => typeof s !== "string" || s.trim() === "")) throw new Error(`${name} is a list of names`);
        const names = [...new Set((v as string[]).map((s) => s.trim()))];
        if (field.kind === "logins") {
          const bad = names.find((s) => !LOGIN.test(s) || s.includes(".."));
          if (bad !== undefined) throw new Error(`${name}: ${JSON.stringify(bad)} is no forge login`);
        }
        body[name] = names;
        break;
      }
    }
  }
  return body;
}

/** The fields of a call that are protection fields: every argument but owner, repo, branch and why. */
export function givenFields(args: Record<string, unknown>): string[] {
  return Object.keys(args).filter((k) => !["owner", "repo", "branch", "why"].includes(k) && args[k] !== undefined);
}

/** A rule as the controller reads it from gitea_branch_protection_get (protectionRule in build_source.go). */
interface ControllerRule { rule: string; push: boolean; admin_may_override: boolean; merge_whitelist: string[] | null }

function asControllerRule(p: BranchProtection): ControllerRule {
  return {
    rule: String(p.rule_name ?? p.branch_name ?? ""),
    push: p.enable_push ?? false,
    admin_may_override: !(p.block_admin_merge_override ?? false),
    merge_whitelist: p.enable_merge_whitelist ? (p.merge_whitelist_usernames ?? []) : null,
  };
}

/** ruleCovers of build_source.go, as the controller reads a rule's glob: `**` any, `*` within a segment, `?` one. */
function controllerCovers(rule: string, branch: string): boolean {
  if (rule === branch) return true;
  if (!/[*?[]/.test(rule)) return false;
  let re = "^";
  for (let i = 0; i < rule.length; i++) {
    const c = rule[i];
    if (c === "*" && rule[i + 1] === "*") { re += ".*"; i++; }
    else if (c === "*") re += "[^/]*";
    else if (c === "?") re += "[^/]";
    else re += c.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
  }
  return new RegExp(re + "$").test(branch);
}

/** Whether the controller registers a module from this branch, judged as judgedRule in mesh-control
 *  cmd/mesh-controller/build_source.go does (ADR 0534 §6): the rule named for the branch, else the first glob rule that
 *  covers it; it takes no push, its merge whitelist names mesh-tools and no agent-<node>, and no administrator merges
 *  past it. A mirror, not the judge: the controller's own verdict is the one that counts. */
export function trunkRule(rules: BranchProtection[], branch: string): { holds: boolean; why: string } {
  const all = rules.map(asControllerRule);
  const r = all.find((x) => x.rule === branch) ?? all.find((x) => controllerCovers(x.rule, branch));
  const no = (why: string) => ({ holds: false, why });
  if (!r) return no(`no protection rule covers ${branch}`);
  if (r.push) return no(`the rule ${r.rule} lets a person push to ${branch} directly`);
  if (!r.merge_whitelist || r.merge_whitelist.length === 0) {
    return no(`the rule ${r.rule} keeps no merge whitelist naming ${TOOLS_ACCOUNT} alone for ${branch}`);
  }
  if (!r.merge_whitelist.includes(TOOLS_ACCOUNT)) {
    return no(`the rule ${r.rule} lets ${r.merge_whitelist.join(", ")} merge into ${branch}, and not ${TOOLS_ACCOUNT}`);
  }
  if (r.merge_whitelist.some((l) => l.startsWith("agent-"))) {
    return no(`the rule ${r.rule} lets an agent's account merge into ${branch}: ${r.merge_whitelist.join(", ")}`);
  }
  if (r.admin_may_override) return no(`the rule ${r.rule} lets an administrator merge into ${branch} past it`);
  return { holds: true, why: `the rule ${r.rule} takes no push, only ${r.merge_whitelist.join(", ")} merge, and no administrator merges past it` };
}