@codyswann/lisa 4.14.0 → 4.15.1

package/plugins/src/base/skills/lisa-doctor/SKILL.md

@@ -629,6 +629,37 @@ choice at all — the value is whatever GitHub's default happens to be. Declarin
 and makes it visible to the reconciler; declaring nothing keeps the payload byte-for-byte what it
 was, parameter absent.
 
+### A ruleset that governs no branch
+
+Reconciliation asks whether the required LIST matches. It never asks whether the ruleset carrying
+that list matches any ref the repository actually has, and GitHub does not ask either: a
+`conditions.ref_name.include` entry is a pattern, not a reference, so `refs/heads/dev` is accepted
+and stays live on a repository whose only branch is `main`. Everything that ruleset requires is then
+required nowhere — the gate still runs and posts its context, and no pull request waits on it.
+
+Every surface read that as healthy. `compareRulesets` in `lisa health` compares the include list
+against Lisa's template by string equality, and both say `refs/heads/dev`, therefore no drift; the
+repo-map row parses includes but matches the literal `~DEFAULT_BRANCH` and ORs across rows, so one
+governing ruleset makes the whole answer green. Nothing enumerated the repository's branches.
+
+The `github.ruleset-reach` check in `lisa health` now does, and so does
+`scripts/lisa-github-rulesets.sh` at the end of every apply, dry run included. Both load one shipped
+detector, `scripts/lisa-ruleset-reach.mjs`, so the two surfaces cannot disagree about which rulesets
+govern nothing. Not in doctor: doctor makes no network call, and which branches exist is a live
+read — the same split that puts the template half of the declaration comparison in doctor and the
+live half in health.
+
+Three answers, never two. A ruleset that matches at least one branch is silent. One that matches
+none is named with the patterns that matched nothing. One this run could not classify — an
+unreadable branch list, a `~DEFAULT_BRANCH` whose default branch could not be resolved, an fnmatch
+bracket expression the detector does not model — is `undetermined` and says so, because an unread
+branch list is not an empty repository and reporting it as one would name every ruleset present.
+
+**Report only, and neither obvious repair is Lisa's to make.** Creating the missing branch
+manufactures the very ref the ruleset was written to protect; disabling the ruleset gives up a
+protection somebody chose. An automated actor may narrow a control, never loosen one. Point the
+ruleset at a branch the repository has, or retire it deliberately.
+
 ## Secrets configuration
 
 Run the secrets health checks through the skill that owns the contract, rather than reimplementing

package/scripts/lisa-github-rulesets.sh

@@ -933,26 +933,32 @@ collect_templates() {
 # a repository may legitimately require a status posted by a third-party app or
 # by a job its own CI defines, and a sweep that flagged every externally
 # produced context would be noise an operator learns to ignore.
-report_retired_contexts() {
+# Fetch every ruleset's DETAIL payload once, for every report-only sweep.
+#
+# The LIST endpoint answers with summaries: id, name, enforcement — and no
+# `rules` and no `conditions`. A sweep run over the list would therefore find
+# nothing on every repository, always, and report it as clean. Each ruleset's
+# required checks and ref conditions only exist on its detail payload, so each
+# one is fetched, and a detail this run could not read is stated rather than
+# skipped.
+#
+# Fetched once and shared. Two sweeps now read the same details — one for
+# retired required contexts, one for branch reach — and fetching twice would
+# double a bounded N+1 of API calls for an answer that cannot differ between
+# them, then report the same unreadable ruleset to the operator twice.
+#
+# Writes the JSON array to $3 rather than stdout, because the warnings it emits
+# for an unreadable ruleset are themselves stdout and would otherwise land in
+# the middle of the payload.
+fetch_ruleset_details() {
   local repo="$1"
   local rulesets="$2"
-  local registry="$LISA_ROOT/all/copy-overwrite/scripts/lisa-gates.mjs"
-  local retired
+  local outfile="$3"
 
-  # An unread retirement list is NOT "no retired contexts". Saying nothing here
-  # would report a repository clean on the strength of a read that never
-  # happened, which is the same defect one layer up.
-  if [[ ! -f "$registry" ]]; then
-    log_warning "Could not read $registry — retired required contexts were NOT checked. This is not a clean result."
-    return 0
-  fi
-  if ! retired=$(node "$registry" retired-contexts 2>/dev/null); then
-    log_warning "Could not derive the retired-context list — retired required contexts were NOT checked. This is not a clean result."
-    return 0
-  fi
-
-  # Likewise for the other side of the comparison: zero rulesets read and a
-  # repository with nothing required look identical from here.
+  # Zero rulesets read and a repository with nothing required look identical
+  # from here, and the empty one is the more likely: a token without the
+  # ruleset scope, an organization-level ruleset this reader cannot see, and a
+  # repository with no protection all arrive as zero rows.
   local -a ids=()
   if [[ -n "$rulesets" ]]; then
     while IFS= read -r id; do
@@ -960,24 +966,43 @@ report_retired_contexts() {
     done < <(echo "$rulesets" | jq -r '.[].id // empty')
   fi
   if [[ ${#ids[@]} -eq 0 ]]; then
-    log_warning "No rulesets were readable — retired required contexts were NOT checked. This is not a clean result."
-    return 0
+    log_warning "No rulesets were readable — retired required contexts and ruleset branch reach were NOT checked. This is not a clean result."
+    return 1
   fi
 
-  # The LIST endpoint answers with summaries: id, name, enforcement — and no
-  # `rules`. A sweep run over the list would therefore find nothing on every
-  # repository, always, and report it as clean. Each ruleset's required checks
-  # only exist on its detail payload, so each one is fetched, and a detail this
-  # run could not read is stated rather than skipped.
   local details="[]"
   local id detail
   for id in "${ids[@]}"; do
     if ! detail=$(gh api -X GET "repos/$repo/rulesets/$id" 2>/dev/null); then
-      log_warning "Ruleset $id could not be read — retired required contexts were NOT checked for it. This is not a clean result."
+      log_warning "Ruleset $id could not be read — retired required contexts and branch reach were NOT checked for it. This is not a clean result."
       continue
     fi
     details=$(jq -c -n --argjson all "$details" --argjson one "$detail" '$all + [$one]')
   done
+  printf '%s' "$details" > "$outfile"
+  return 0
+}
+
+report_retired_contexts() {
+  local details_file="$1"
+  local registry="$LISA_ROOT/all/copy-overwrite/scripts/lisa-gates.mjs"
+  local retired
+
+  # An unread retirement list is NOT "no retired contexts". Saying nothing here
+  # would report a repository clean on the strength of a read that never
+  # happened, which is the same defect one layer up.
+  if [[ ! -f "$registry" ]]; then
+    log_warning "Could not read $registry — retired required contexts were NOT checked. This is not a clean result."
+    return 0
+  fi
+  if ! retired=$(node "$registry" retired-contexts 2>/dev/null); then
+    log_warning "Could not derive the retired-context list — retired required contexts were NOT checked. This is not a clean result."
+    return 0
+  fi
+
+  [[ -s "$details_file" ]] || return 0
+  local details
+  details=$(cat "$details_file")
 
   # Matched on the retired LABEL as the final context segment, never on the
   # whole context string. A check run's reported name is the `/`-joined chain
@@ -1034,6 +1059,94 @@ report_retired_contexts() {
   echo ""
 }
 
+##############################################################################
+# Ruleset Branch Reach
+##############################################################################
+
+# Report every ruleset whose include patterns match NO branch this repository
+# has. CodySwannGT/lisa#2781.
+#
+# GitHub accepts an include entry naming a branch that does not exist — the
+# entries are patterns, not references, and nothing on either side validates
+# them. So a ruleset can be live, active, and governing nothing, and every
+# surface reads it as healthy: `compareRulesets` in `src/health` holds the
+# template against the live ruleset by string equality, and both say
+# `refs/heads/dev`, therefore not drifted, therefore fine.
+#
+# The cost is paid by whoever merges next. A required context is only required
+# on the refs the ruleset matches, so a gate whose ruleset matches nothing is a
+# gate that reports and blocks no one — and the operator learns which of those
+# two it is at the moment they are blocked, or never. This moves it earlier.
+#
+# REPORT ONLY, like the sweep above and for a stronger reason. The two obvious
+# repairs — create the missing branch, or disable the ruleset — are both an
+# automated actor LOOSENING a control nobody asked it to loosen: the first
+# manufactures the very ref the ruleset exists to protect, the second gives up
+# a protection somebody chose. Neither is this script's decision.
+report_zero_reach_rulesets() {
+  local repo="$1"
+  local details_file="$2"
+  local detector="$LISA_ROOT/scripts/lisa-ruleset-reach.mjs"
+
+  if [[ ! -f "$detector" ]]; then
+    log_warning "Could not read $detector — ruleset branch reach was NOT checked. This is not a clean result."
+    return 0
+  fi
+  [[ -s "$details_file" ]] || return 0
+
+  # An unread branch list is NOT an empty repository, and the difference is the
+  # whole point: comparing include patterns against zero branches would report
+  # EVERY ruleset as governing nothing, which is noise an operator learns to
+  # ignore and is how a real one stops being read.
+  local branch_pages branch_names
+  if ! branch_pages=$(gh api --paginate "repos/$repo/branches?per_page=100" 2>/dev/null); then
+    log_warning "Could not list this repository's branches — ruleset branch reach was NOT checked. This is not a clean result."
+    return 0
+  fi
+  # `--paginate` emits one JSON array PER PAGE rather than one merged array, so
+  # this filter is applied to a stream of arrays; jq reads each top-level value
+  # in turn, which is exactly the shape needed. A filter written for a single
+  # array would silently read page one only.
+  if ! branch_names=$(jq -r '.[] | .name? // empty' <<< "$branch_pages" 2>/dev/null); then
+    log_warning "Could not read this repository's branch list — ruleset branch reach was NOT checked. This is not a clean result."
+    return 0
+  fi
+  if [[ -z "$branch_names" ]]; then
+    log_warning "No branch was readable — ruleset branch reach was NOT checked. This is not a clean result."
+    return 0
+  fi
+
+  # Read separately, and NOT defaulted when unreadable. `~DEFAULT_BRANCH` is
+  # the include entry most rulesets rely on, and guessing which branch it names
+  # would decide the whole verdict from a guess. The detector answers
+  # `undetermined` for a ruleset it cannot resolve it for.
+  local default_branch=""
+  default_branch=$(gh api "repos/$repo" --jq '.default_branch' 2>/dev/null) || default_branch=""
+
+  local branches_file report
+  branches_file=$(mktemp)
+  printf '%s\n' "$branch_names" > "$branches_file"
+  # A detector that could not run is NOT a repository with nothing to report.
+  # Reading its failure as silence is the same defect one layer up, sited on
+  # the detector built to catch it.
+  if ! report=$(node "$detector" \
+    --rulesets="$details_file" \
+    --branches="$branches_file" \
+    --default-branch="$default_branch" 2>/dev/null); then
+    rm -f "$branches_file"
+    log_warning "The ruleset reach detector could not run — ruleset branch reach was NOT checked. This is not a clean result."
+    return 0
+  fi
+  rm -f "$branches_file"
+
+  if [[ -z "$report" ]]; then
+    log_verbose "Every ruleset in this repository governs at least one branch."
+    return 0
+  fi
+  echo ""
+  echo "$report"
+}
+
 main() {
   # Parse arguments
   while [[ $# -gt 0 ]]; do
@@ -1171,10 +1284,17 @@ main() {
     fi
   done
 
-  # Runs whatever the apply did, dry-run included. The retired name lives in a
-  # ruleset the apply above never touched, so an apply that "succeeded" is
-  # exactly the run that most needs to say this.
-  report_retired_contexts "$repo" "$existing_rulesets"
+  # Both sweeps run whatever the apply did, dry-run included, and both read the
+  # SAME detail payloads. What they report lives in rulesets the apply above
+  # never touched, so an apply that "succeeded" is exactly the run that most
+  # needs to say this.
+  local ruleset_details
+  ruleset_details=$(mktemp)
+  if fetch_ruleset_details "$repo" "$existing_rulesets" "$ruleset_details"; then
+    report_retired_contexts "$ruleset_details"
+    report_zero_reach_rulesets "$repo" "$ruleset_details"
+  fi
+  rm -f "$ruleset_details"
 
   echo ""
   if [[ "$DRY_RUN" == "true" ]]; then