create-interview-cockpit 0.27.0 → 0.28.0

package/template/client/src/codeowners.ts

@@ -0,0 +1,792 @@
+// ─── CODEOWNERS parser, evaluator, and roster helpers ──────────────────
+//
+// This module is a small, self-contained imitation of the CODEOWNERS
+// engine GitHub runs on every pull request. It powers:
+//
+//   1. Live validation in the Monaco editor when the user opens the
+//      CODEOWNERS file (unknown owners, bad globs, comments, blank lines).
+//   2. The "Pull Request" tab — given a set of changed files, work out
+//      which rule (if any) wins for each file and which logins/teams get
+//      auto-requested as reviewers.
+//   3. The "merge box" — combine CODEOWNERS results with branch
+//      protection rules to decide if the PR is mergeable.
+//   4. Console messages emitted by the server when an `act push` or
+//      `act pull_request` event runs in the lab.
+//
+// References / behaviour mirrored:
+//   - LAST matching rule wins (https://docs.github.com/repositories/
+//     managing-your-repositories-settings-and-features/customizing-your-
+//     repository/about-code-owners#codeowners-syntax).
+//   - Blank lines and `# comments` are ignored.
+//   - A rule with no owners explicitly clears ownership for the matched
+//     pattern (used to "unprotect" sub-paths).
+//   - Owner handles look like `@user`, `@org/team`, or `email@host`.
+//
+// We intentionally support a useful subset of glob features rather than
+// re-implementing GitHub's exact matcher: `*`, `**`, `?`, leading `/`,
+// trailing `/` (folder-only). That covers ~all real CODEOWNERS rules.
+
+import type {
+  GithubLabOrg,
+  GithubLabTeam,
+  GithubLabPullRequest,
+  GithubLabBranchProtection,
+  GithubLabReview,
+  GithubLabCheckRun,
+  GithubLabRuleset,
+  GithubLabRulesetRules,
+} from "./types";
+
+// ─── Parsing ───────────────────────────────────────────────────────────
+
+export interface CodeOwnersRule {
+  /** 1-based line number in the source file (for editor markers). */
+  line: number;
+  /** Raw line text (after comment stripping) — handy for debugging. */
+  raw: string;
+  /** The glob pattern as written by the user (e.g. `src/**` or `*.ts`). */
+  pattern: string;
+  /** Owner handles (without leading `@`) — empty array means "no owners". */
+  owners: string[];
+}
+
+export interface CodeOwnersIssue {
+  line: number;
+  severity: "error" | "warning";
+  message: string;
+}
+
+export interface CodeOwnersParseResult {
+  rules: CodeOwnersRule[];
+  issues: CodeOwnersIssue[];
+}
+
+const HANDLE_RE =
+  /^@?[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})(?:\/[A-Za-z0-9][A-Za-z0-9-]{0,38})?$/;
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/** Parse a CODEOWNERS file body into ordered rules + diagnostics. */
+export function parseCodeOwners(text: string): CodeOwnersParseResult {
+  const rules: CodeOwnersRule[] = [];
+  const issues: CodeOwnersIssue[] = [];
+  const lines = text.split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const rawLine = lines[i] ?? "";
+    // Strip inline `# comment` but keep escaped `\#`.
+    let stripped = "";
+    for (let c = 0; c < rawLine.length; c += 1) {
+      const ch = rawLine[c];
+      if (ch === "#" && rawLine[c - 1] !== "\\") break;
+      stripped += ch;
+    }
+    const trimmed = stripped.trim();
+    if (!trimmed) continue;
+
+    const tokens = trimmed.split(/\s+/);
+    const pattern = tokens[0] ?? "";
+    const owners = tokens.slice(1);
+
+    if (!pattern) continue;
+
+    // Pattern sanity check: must contain at least one path-y character.
+    if (/[\\]/.test(pattern)) {
+      issues.push({
+        line: i + 1,
+        severity: "warning",
+        message: `Pattern "${pattern}" uses a backslash; CODEOWNERS expects forward slashes.`,
+      });
+    }
+
+    // Validate owner shapes (don't yet check if they exist — that's
+    // a separate pass that needs the roster).
+    for (const o of owners) {
+      const handle = o.startsWith("@") ? o.slice(1) : o;
+      const looksLikeEmail = EMAIL_RE.test(o);
+      const looksLikeHandle = HANDLE_RE.test(handle);
+      if (!looksLikeEmail && !looksLikeHandle) {
+        issues.push({
+          line: i + 1,
+          severity: "error",
+          message: `Owner "${o}" is not a valid @user, @org/team, or email.`,
+        });
+      }
+    }
+
+    rules.push({
+      line: i + 1,
+      raw: stripped,
+      pattern,
+      owners: owners.map((o) => (o.startsWith("@") ? o.slice(1) : o)),
+    });
+  }
+
+  return { rules, issues };
+}
+
+/**
+ * Cross-check parsed rules against the lab's fake org roster. Any owner
+ * that does not resolve to a known user, team, or email gets a warning
+ * marker. This is the "your reviewers don't exist" hint a real GitHub
+ * org sees in the CODEOWNERS settings page.
+ */
+export function lintCodeOwnersAgainstOrg(
+  parsed: CodeOwnersParseResult,
+  org: GithubLabOrg | undefined,
+): CodeOwnersIssue[] {
+  if (!org) return parsed.issues;
+  const knownUsers = new Set(org.users.map((u) => u.toLowerCase()));
+  const knownTeams = new Set(
+    org.teams.map((t) => `${org.slug.toLowerCase()}/${t.slug.toLowerCase()}`),
+  );
+  const extra: CodeOwnersIssue[] = [];
+  for (const rule of parsed.rules) {
+    for (const owner of rule.owners) {
+      if (EMAIL_RE.test(owner)) continue; // emails are always opaque.
+      if (owner.includes("/")) {
+        if (!knownTeams.has(owner.toLowerCase())) {
+          extra.push({
+            line: rule.line,
+            severity: "warning",
+            message: `Team @${owner} is not in the lab roster.`,
+          });
+        }
+      } else if (!knownUsers.has(owner.toLowerCase())) {
+        extra.push({
+          line: rule.line,
+          severity: "warning",
+          message: `User @${owner} is not in the lab roster.`,
+        });
+      }
+    }
+  }
+  return [...parsed.issues, ...extra];
+}
+
+// ─── Glob matching ─────────────────────────────────────────────────────
+
+/**
+ * Convert a CODEOWNERS-style glob into a RegExp. Supports `*` (single
+ * segment wildcard), `**` (multi-segment), `?` (single char), leading
+ * `/` (root-anchored), trailing `/` (folder + anything inside).
+ */
+export function codeOwnersPatternToRegExp(pattern: string): RegExp {
+  let p = pattern;
+  const rootAnchored = p.startsWith("/");
+  if (rootAnchored) p = p.slice(1);
+
+  // Folder-only patterns (trailing slash) match the folder and anything
+  // beneath it.
+  const folderOnly = p.endsWith("/");
+  if (folderOnly) p = p.slice(0, -1);
+
+  // Tokenise so `**` is treated atomically before `*`.
+  let re = "";
+  for (let i = 0; i < p.length; i += 1) {
+    const c = p[i];
+    if (c === "*" && p[i + 1] === "*") {
+      re += ".*";
+      i += 1;
+    } else if (c === "*") {
+      re += "[^/]*";
+    } else if (c === "?") {
+      re += "[^/]";
+    } else if (/[.+^${}()|[\]\\]/.test(c ?? "")) {
+      re += `\\${c}`;
+    } else {
+      re += c;
+    }
+  }
+
+  if (folderOnly) re += "(?:/.*)?";
+
+  // Root-anchored: must match from start.
+  // Non-anchored: behave like gitignore — match against any path segment.
+  const anchored = rootAnchored ? `^${re}$` : `(?:^|/)${re}(?:/.*)?$`;
+
+  return new RegExp(anchored);
+}
+
+// ─── Evaluation ────────────────────────────────────────────────────────
+
+export interface CodeOwnersMatch {
+  /** Path that was evaluated. */
+  path: string;
+  /** Rule that won (last match wins). undefined when no rule matched. */
+  rule?: CodeOwnersRule;
+  /** Resolved logins (users) after expanding teams. */
+  resolvedReviewers: string[];
+  /** The raw owner handles from the winning rule (for display). */
+  owners: string[];
+}
+
+export interface CodeOwnersEvaluation {
+  perFile: CodeOwnersMatch[];
+  /** Unique owner handles across all matched files (e.g. `@frontend`, `@octocat`). */
+  requestedHandles: string[];
+  /** Unique resolved logins (without @) — these are the people pinged. */
+  requestedReviewers: string[];
+  /** Files that have at least one CODEOWNERS rule matching them. */
+  ownedFiles: string[];
+  /** Files with no matching rule. */
+  unownedFiles: string[];
+}
+
+export function evaluateCodeOwners(
+  rules: CodeOwnersRule[],
+  changedFiles: string[],
+  org?: GithubLabOrg,
+): CodeOwnersEvaluation {
+  const compiled = rules.map((r) => ({
+    rule: r,
+    re: codeOwnersPatternToRegExp(r.pattern),
+  }));
+
+  const perFile: CodeOwnersMatch[] = changedFiles.map((path) => {
+    // Last match wins — iterate in reverse.
+    let winner: CodeOwnersRule | undefined;
+    for (let i = compiled.length - 1; i >= 0; i -= 1) {
+      const c = compiled[i];
+      if (c && c.re.test(path)) {
+        winner = c.rule;
+        break;
+      }
+    }
+    const owners = winner?.owners ?? [];
+    const resolved = resolveOwnersToLogins(owners, org);
+    return {
+      path,
+      ...(winner ? { rule: winner } : {}),
+      owners,
+      resolvedReviewers: resolved,
+    };
+  });
+
+  const handleSet = new Set<string>();
+  const reviewerSet = new Set<string>();
+  const ownedFiles: string[] = [];
+  const unownedFiles: string[] = [];
+
+  for (const m of perFile) {
+    if (m.rule && m.owners.length > 0) {
+      ownedFiles.push(m.path);
+      m.owners.forEach((h) => handleSet.add(h));
+      m.resolvedReviewers.forEach((r) => reviewerSet.add(r));
+    } else {
+      unownedFiles.push(m.path);
+    }
+  }
+
+  return {
+    perFile,
+    requestedHandles: [...handleSet].sort(),
+    requestedReviewers: [...reviewerSet].sort(),
+    ownedFiles,
+    unownedFiles,
+  };
+}
+
+/** Expand `@org/team` handles into individual logins via the roster. */
+export function resolveOwnersToLogins(
+  owners: string[],
+  org?: GithubLabOrg,
+): string[] {
+  if (!owners.length) return [];
+  const out = new Set<string>();
+  for (const owner of owners) {
+    if (EMAIL_RE.test(owner)) continue; // emails don't map to logins.
+    if (owner.includes("/")) {
+      const [orgSlug, teamSlug] = owner.split("/");
+      const team = findTeam(org, orgSlug ?? "", teamSlug ?? "");
+      team?.members.forEach((m) => out.add(m));
+    } else {
+      out.add(owner);
+    }
+  }
+  return [...out];
+}
+
+function findTeam(
+  org: GithubLabOrg | undefined,
+  orgSlug: string,
+  teamSlug: string,
+): GithubLabTeam | undefined {
+  if (!org) return undefined;
+  if (org.slug.toLowerCase() !== orgSlug.toLowerCase()) return undefined;
+  return org.teams.find((t) => t.slug.toLowerCase() === teamSlug.toLowerCase());
+}
+
+// ─── Reviews ───────────────────────────────────────────────────────────
+
+/**
+ * Collapse a review log into the *current* state per reviewer — only
+ * the latest review by each author counts toward merge protection on
+ * github.com, so we mirror that here.
+ *
+ * The PR author's own reviews are ignored (you can't review your own PR).
+ */
+export function latestReviewByAuthor(
+  reviews: GithubLabReview[] | undefined,
+  viewerLogin?: string,
+): Map<string, GithubLabReview> {
+  const out = new Map<string, GithubLabReview>();
+  if (!reviews?.length) return out;
+  const sorted = [...reviews].sort(
+    (a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt),
+  );
+  for (const r of sorted) {
+    if (viewerLogin && r.author.toLowerCase() === viewerLogin.toLowerCase()) {
+      continue;
+    }
+    // "commented" reviews never override an existing approve/changes_requested.
+    const existing = out.get(r.author.toLowerCase());
+    if (r.state === "commented" && existing) continue;
+    out.set(r.author.toLowerCase(), r);
+  }
+  return out;
+}
+
+/** Logins that currently sit at state="approved" in the review log. */
+export function approvedLogins(
+  reviews: GithubLabReview[] | undefined,
+  viewerLogin?: string,
+): string[] {
+  const latest = latestReviewByAuthor(reviews, viewerLogin);
+  return [...latest.values()]
+    .filter((r) => r.state === "approved")
+    .map((r) => r.author);
+}
+
+/** Logins that currently sit at state="changes_requested". */
+export function changesRequestedLogins(
+  reviews: GithubLabReview[] | undefined,
+  viewerLogin?: string,
+): string[] {
+  const latest = latestReviewByAuthor(reviews, viewerLogin);
+  return [...latest.values()]
+    .filter((r) => r.state === "changes_requested")
+    .map((r) => r.author);
+}
+
+// ─── Mergeability ──────────────────────────────────────────────────────
+
+export interface CheckStatus {
+  name: string;
+  status: "success" | "failed" | "pending" | "missing";
+}
+
+export interface MergeabilityResult {
+  mergeable: boolean;
+  reasons: string[];
+  /** Owners still needed for required-CODEOWNERS approval, by file path. */
+  pendingOwnersByFile: Record<string, string[]>;
+  /** Count of approvals already collected. */
+  approvalCount: number;
+  /** How many more approvals are required overall. */
+  approvalsRemaining: number;
+  /** Logins who have actively requested changes (blocks merge). */
+  changesRequestedBy: string[];
+  /** Required status checks resolved against the latest run. */
+  checkStatuses: CheckStatus[];
+  /** Active rulesets that affected the result (for the UI summary). */
+  appliedRulesets: GithubLabRuleset[];
+  /** Combined effective rules — used by the PR sidebar to show config. */
+  effectiveRules: GithubLabRulesetRules;
+  /** Reasons that come from rulesets in `evaluate` mode (warning-only). */
+  evaluateOnlyReasons: string[];
+  /** Informational notes for rules the lab can't fully simulate. */
+  informationalNotes: string[];
+}
+
+// ─── Ruleset matching ──────────────────────────────────────────────────
+//
+// GitHub uses fnmatch-style globs for ruleset targeting plus a couple of
+// special tokens. We support `~ALL` (every ref), `~DEFAULT_BRANCH`,
+// literal names, and the same `*` / `**` / `?` globs CODEOWNERS uses.
+
+function matchesBranchPattern(
+  pattern: string,
+  branch: string,
+  defaultBranch: string,
+): boolean {
+  if (!pattern) return false;
+  if (pattern === "~ALL") return true;
+  if (pattern === "~DEFAULT_BRANCH") return branch === defaultBranch;
+  if (pattern === branch) return true;
+  return codeOwnersPatternToRegExp(pattern).test(branch);
+}
+
+/**
+ * Pick the rulesets that affect a PR targeting `branch`, honoring
+ * enforcement state and the bypass list. Disabled rulesets are filtered
+ * out entirely; `evaluate` rulesets are kept so the UI can render them
+ * as warnings instead of hard blockers.
+ */
+export function getApplicableRulesets(
+  rulesets: GithubLabRuleset[] | undefined,
+  branch: string,
+  defaultBranch: string,
+  org?: GithubLabOrg,
+): GithubLabRuleset[] {
+  if (!rulesets || rulesets.length === 0) return [];
+  const viewer = org?.viewerLogin?.toLowerCase();
+  return rulesets.filter((rs) => {
+    if (rs.enforcement === "disabled") return false;
+    const included = rs.targetInclude.some((p) =>
+      matchesBranchPattern(p, branch, defaultBranch),
+    );
+    if (!included) return false;
+    const excluded = (rs.targetExclude ?? []).some((p) =>
+      matchesBranchPattern(p, branch, defaultBranch),
+    );
+    if (excluded) return false;
+    if (viewer) {
+      const bypassed = (rs.bypass ?? []).some((handle) => {
+        const logins = resolveOwnersToLogins([handle], org);
+        return logins.some((l) => l.toLowerCase() === viewer);
+      });
+      if (bypassed) return false;
+    }
+    return true;
+  });
+}
+
+/**
+ * Combine the rules from several rulesets into one effective rule bag.
+ * GitHub takes the strictest constraint when rulesets overlap, so we
+ * OR booleans, take the max of the approving-review count, and union
+ * the status-check name lists / environment lists / scanning tools.
+ */
+export function mergeRules(
+  rulesets: GithubLabRuleset[],
+): GithubLabRulesetRules {
+  const out: GithubLabRulesetRules = {};
+  for (const rs of rulesets) {
+    const r = rs.rules;
+    if (r.restrictCreations) out.restrictCreations = true;
+    if (r.restrictUpdates) out.restrictUpdates = true;
+    if (r.restrictDeletions) out.restrictDeletions = true;
+    if (r.requireLinearHistory) out.requireLinearHistory = true;
+    if (r.requireSignedCommits) out.requireSignedCommits = true;
+    if (r.blockForcePushes) out.blockForcePushes = true;
+    if (r.requireCodeQuality) out.requireCodeQuality = true;
+    if (r.pullRequest) {
+      const cur = out.pullRequest ?? {
+        requiredApprovingReviewCount: 0,
+        requireCodeOwnerReview: false,
+        dismissStaleReviewsOnPush: false,
+        requireLastPushApproval: false,
+      };
+      out.pullRequest = {
+        requiredApprovingReviewCount: Math.max(
+          cur.requiredApprovingReviewCount,
+          r.pullRequest.requiredApprovingReviewCount,
+        ),
+        requireCodeOwnerReview:
+          cur.requireCodeOwnerReview || r.pullRequest.requireCodeOwnerReview,
+        dismissStaleReviewsOnPush:
+          cur.dismissStaleReviewsOnPush ||
+          r.pullRequest.dismissStaleReviewsOnPush,
+        requireLastPushApproval:
+          cur.requireLastPushApproval || r.pullRequest.requireLastPushApproval,
+      };
+    }
+    if (r.statusChecks) {
+      const cur = out.statusChecks ?? { checks: [], strict: false };
+      out.statusChecks = {
+        checks: Array.from(
+          new Set([...(cur.checks ?? []), ...(r.statusChecks.checks ?? [])]),
+        ),
+        strict: cur.strict || r.statusChecks.strict,
+      };
+    }
+    if (r.requireDeployments) {
+      const cur = out.requireDeployments ?? { environments: [] };
+      out.requireDeployments = {
+        environments: Array.from(
+          new Set([...cur.environments, ...r.requireDeployments.environments]),
+        ),
+      };
+    }
+    if (r.requireCodeScanning) {
+      const cur = out.requireCodeScanning ?? { tools: [] };
+      out.requireCodeScanning = {
+        tools: Array.from(
+          new Set([...cur.tools, ...r.requireCodeScanning.tools]),
+        ),
+      };
+    }
+  }
+  return out;
+}
+
+export function evaluateMergeability(
+  evaluation: CodeOwnersEvaluation,
+  pr: GithubLabPullRequest,
+  rulesets: GithubLabRuleset[] | undefined,
+  org: GithubLabOrg | undefined,
+  baseBranch: string,
+  defaultBranch: string,
+): MergeabilityResult {
+  const reasons: string[] = [];
+  const evaluateOnlyReasons: string[] = [];
+  const informationalNotes: string[] = [];
+  const viewer = org?.viewerLogin;
+
+  const applicable = getApplicableRulesets(
+    rulesets,
+    baseBranch,
+    defaultBranch,
+    org,
+  );
+  const enforced = applicable.filter((r) => r.enforcement === "active");
+  const evaluateOnly = applicable.filter((r) => r.enforcement === "evaluate");
+  const enforcedRules = mergeRules(enforced);
+  const evaluateRules = mergeRules(evaluateOnly);
+  const effectiveRules = mergeRules(applicable);
+
+  // Reviews drive approvals; fall back to legacy `approvals` for old labs.
+  const approved = pr.reviews
+    ? approvedLogins(pr.reviews, viewer)
+    : (pr.approvals ?? []).filter(
+        (a) => !viewer || a.toLowerCase() !== viewer.toLowerCase(),
+      );
+  const approvedSet = new Set(approved.map((a) => a.toLowerCase()));
+  const changesRequestedBy = changesRequestedLogins(pr.reviews, viewer);
+
+  // ── Pull-request rule (required reviews + code owners) ────────
+  const prRule = enforcedRules.pullRequest;
+  const prRuleEval = evaluateRules.pullRequest;
+  const requiredCount = prRule?.requiredApprovingReviewCount ?? 0;
+  const approvalsRemaining = Math.max(0, requiredCount - approvedSet.size);
+  if (approvalsRemaining > 0) {
+    reasons.push(
+      `Need ${approvalsRemaining} more approving review${
+        approvalsRemaining === 1 ? "" : "s"
+      } (have ${approvedSet.size}/${requiredCount}).`,
+    );
+  } else if (prRuleEval && !prRule) {
+    const evalRemaining = Math.max(
+      0,
+      prRuleEval.requiredApprovingReviewCount - approvedSet.size,
+    );
+    if (evalRemaining > 0) {
+      evaluateOnlyReasons.push(
+        `Would need ${evalRemaining} more approving review${
+          evalRemaining === 1 ? "" : "s"
+        } when ruleset is enforced.`,
+      );
+    }
+  }
+
+  // "Changes requested" reviews always block, regardless of ruleset.
+  if (changesRequestedBy.length > 0) {
+    reasons.push(
+      `Changes requested by ${changesRequestedBy
+        .map((a) => `@${a}`)
+        .join(", ")}.`,
+    );
+  }
+
+  // ── CODEOWNERS approval per matched file ──────────────────────
+  const pendingOwnersByFile: Record<string, string[]> = {};
+  const requireCO =
+    !!prRule?.requireCodeOwnerReview || !!prRuleEval?.requireCodeOwnerReview;
+  if (requireCO) {
+    for (const match of evaluation.perFile) {
+      if (!match.rule || match.owners.length === 0) continue;
+      const stillNeeded = match.owners.filter((handle) => {
+        const reviewers = resolveOwnersToLogins([handle], org);
+        return !reviewers.some((r) => approvedSet.has(r.toLowerCase()));
+      });
+      if (stillNeeded.length > 0) {
+        pendingOwnersByFile[match.path] = stillNeeded;
+      }
+    }
+    const filesPending = Object.keys(pendingOwnersByFile).length;
+    if (filesPending > 0) {
+      const msg = `Code owner review required on ${filesPending} file${
+        filesPending === 1 ? "" : "s"
+      }.`;
+      if (prRule?.requireCodeOwnerReview) reasons.push(msg);
+      else if (prRuleEval?.requireCodeOwnerReview)
+        evaluateOnlyReasons.push(msg);
+    }
+  }
+
+  // ── Required status checks ────────────────────────────────────
+  const required = enforcedRules.statusChecks?.checks ?? [];
+  const requiredEval = evaluateRules.statusChecks?.checks ?? [];
+  const allRequired = Array.from(new Set([...required, ...requiredEval]));
+  const jobByName = new Map<string, GithubLabCheckRun["jobs"][number]>();
+  for (const j of pr.lastCheckRun?.jobs ?? []) {
+    jobByName.set(j.name, j);
+  }
+  const checkStatuses: CheckStatus[] = allRequired.map((name) => {
+    const job = jobByName.get(name);
+    if (!job) return { name, status: "missing" };
+    if (job.status === "success") return { name, status: "success" };
+    if (job.status === "failed" || job.status === "cancelled")
+      return { name, status: "failed" };
+    return { name, status: "pending" };
+  });
+  const failingEnforced = checkStatuses.filter(
+    (c) => required.includes(c.name) && c.status !== "success",
+  );
+  if (failingEnforced.length > 0) {
+    reasons.push(
+      `${failingEnforced.length} required check${
+        failingEnforced.length === 1 ? "" : "s"
+      } not green: ${failingEnforced.map((c) => c.name).join(", ")}.`,
+    );
+  }
+  const failingEvalOnly = checkStatuses.filter(
+    (c) =>
+      !required.includes(c.name) &&
+      requiredEval.includes(c.name) &&
+      c.status !== "success",
+  );
+  if (failingEvalOnly.length > 0) {
+    evaluateOnlyReasons.push(
+      `Status checks would block when enforced: ${failingEvalOnly
+        .map((c) => c.name)
+        .join(", ")}.`,
+    );
+  }
+
+  // ── Required deployments (soft-block: lab can't deploy) ───────
+  const deployRule = enforcedRules.requireDeployments;
+  if (deployRule && deployRule.environments.length > 0) {
+    reasons.push(
+      `Awaiting successful deployment to ${deployRule.environments
+        .map((e) => `\`${e}\``)
+        .join(", ")} (no deploys recorded in lab).`,
+    );
+  }
+
+  // ── Informational rules — surfaced for learning, never blocking ─
+  if (
+    enforcedRules.requireLinearHistory ||
+    evaluateRules.requireLinearHistory
+  ) {
+    informationalNotes.push(
+      "Require linear history: merge commits would be rejected on the protected branch.",
+    );
+  }
+  if (
+    enforcedRules.requireSignedCommits ||
+    evaluateRules.requireSignedCommits
+  ) {
+    informationalNotes.push(
+      "Require signed commits: every push must carry a verified GPG/SSH signature.",
+    );
+  }
+  if (enforcedRules.blockForcePushes || evaluateRules.blockForcePushes) {
+    informationalNotes.push(
+      "Block force pushes: `git push --force` is rejected on this branch.",
+    );
+  }
+  if (enforcedRules.restrictUpdates || evaluateRules.restrictUpdates) {
+    informationalNotes.push(
+      "Restrict updates: only the bypass list can push directly; everyone else must open a pull request.",
+    );
+  }
+  if (enforcedRules.restrictCreations || evaluateRules.restrictCreations) {
+    informationalNotes.push(
+      "Restrict creations: only bypass actors can create matching refs.",
+    );
+  }
+  if (enforcedRules.restrictDeletions || evaluateRules.restrictDeletions) {
+    informationalNotes.push(
+      "Restrict deletions: only bypass actors can delete matching refs.",
+    );
+  }
+  if (enforcedRules.requireCodeScanning || evaluateRules.requireCodeScanning) {
+    const tools =
+      enforcedRules.requireCodeScanning?.tools ??
+      evaluateRules.requireCodeScanning?.tools ??
+      [];
+    informationalNotes.push(
+      `Require code-scanning results${
+        tools.length ? ` from ${tools.join(", ")}` : ""
+      }: GitHub would require alerts to be resolved before merging.`,
+    );
+  }
+  if (enforcedRules.requireCodeQuality || evaluateRules.requireCodeQuality) {
+    informationalNotes.push(
+      "Require code-quality results: configured quality gates must pass before merging.",
+    );
+  }
+
+  return {
+    mergeable: reasons.length === 0,
+    reasons,
+    pendingOwnersByFile,
+    approvalCount: approvedSet.size,
+    approvalsRemaining,
+    changesRequestedBy,
+    checkStatuses,
+    appliedRulesets: applicable,
+    effectiveRules,
+    evaluateOnlyReasons,
+    informationalNotes,
+  };
+}
+
+/**
+ * Bridge for old saved labs (pre-rulesets): turn classic
+ * `branchProtection` into a single active ruleset so the new evaluator
+ * keeps producing the same answer.
+ */
+export function rulesetFromLegacyProtection(
+  protection: GithubLabBranchProtection | undefined,
+  defaultBranch: string,
+): GithubLabRuleset | undefined {
+  if (!protection) return undefined;
+  return {
+    id: "legacy",
+    name: `Default ${defaultBranch} protection`,
+    enforcement: "active",
+    targetInclude: ["~DEFAULT_BRANCH"],
+    targetExclude: [],
+    bypass: [],
+    rules: {
+      pullRequest: {
+        requiredApprovingReviewCount: protection.requiredApprovingReviews,
+        requireCodeOwnerReview: protection.requireCodeOwnerReview,
+        dismissStaleReviewsOnPush: false,
+        requireLastPushApproval: false,
+      },
+      ...(protection.requiredStatusChecks &&
+      protection.requiredStatusChecks.length > 0
+        ? {
+            statusChecks: {
+              checks: protection.requiredStatusChecks,
+              strict: false,
+            },
+          }
+        : {}),
+    },
+  };
+}
+
+// ─── Locating the CODEOWNERS file ──────────────────────────────────────
+
+const CODEOWNERS_LOCATIONS = [
+  ".github/CODEOWNERS",
+  "CODEOWNERS",
+  "docs/CODEOWNERS",
+] as const;
+
+/** Find the first CODEOWNERS path that exists in the workspace, if any. */
+export function findCodeOwnersPath(
+  files: Record<string, string>,
+): string | undefined {
+  return CODEOWNERS_LOCATIONS.find((p) =>
+    Object.prototype.hasOwnProperty.call(files, p),
+  );
+}
+
+export function isCodeOwnersPath(path: string): boolean {
+  return (CODEOWNERS_LOCATIONS as readonly string[]).includes(path);
+}