update-maven-wrapper.yml

name: Update Maven Wrapper

run-name: "${{ (github.event_name != 'schedule' && inputs.check_only == true) && 'Check' || 'Update' }} Maven Wrapper${{ inputs.projects != '' && format(' [{0}]', inputs.projects) || '' }} (${{ inputs.repo_type || 'both' }})${{ (github.event_name != 'schedule' && inputs.check_only != true && inputs.regenerate == false) && ' - Properties Only' || '' }}${{ (github.event_name != 'schedule' && inputs.check_only != true && inputs.dry_run != false) && ' - Dry Run' || '' }}"

# Opens a pull request against every maintained repository/branch whose Maven wrapper is
# behind, so CI decides whether the upgrade is safe rather than a bulk push doing it blind.
#
#   1. versions - resolve the target Maven and maven-wrapper versions
#   2. setup    - read config/projects.json and build one matrix entry per repo/branch
#   3. update   - per repo/branch: compare, and open a PR if it is behind
#   4. summary  - one report covering every combination
#
# Written after GitHub enabled its `maven-wrapper-updater` experiment, which made Dependabot
# start updating the wrapper itself and fail across the estate in two ways:
#
#   * it shells out to `mvn wrapper:wrapper`, which needs to resolve the project's parent
#     POM - and an unpublished SNAPSHOT parent is not resolvable, OSS or commercial
#   * it cannot parse the older wrapper formats at all ("Could not determine Maven Wrapper
#     version from wrapperVersion, wrapperUrl, or script files")
#
# Bringing every wrapper up to a current, consistent version removes both. Note the first
# of those returns whenever a new Maven is released and the wrappers fall behind again -
# this workflow running weekly is what keeps that from becoming an outage.
#
# EVERY wrapper in the repository is in scope, not only the root one. Dependabot looks for
# a wrapper in the directory of every pom it fetches - the root plus each <module> - and
# raises while *parsing* any it cannot read a version out of, which aborts that
# repository's entire update job: no pull requests at all, not merely no wrapper PR. A
# pristine root wrapper therefore buys nothing while a submodule still carries the
# single-line file it was given in 2018, which is the state four repositories were found
# in. Directories with a wrapper but no pom.xml are left alone: Dependabot never reads
# those, so changing them would be churn.
#
# `check_only` runs the audit on its own - it reports every wrapper file Dependabot cannot
# read and fails the run if any exist, changing nothing. That is the canary; the normal
# mode is the fix.
#
# See README-update-maven-wrapper.md for details.

on:
  workflow_dispatch:
    inputs:
      projects:
        description: 'Comma-separated list of Spring Cloud project names. When empty, every project in projects.json is processed.'
        required: false
        type: string
        default: ''
      repo_type:
        description: 'Update commercial, oss, or both?'
        required: false
        type: choice
        default: 'both'
        options:
          - both
          - oss
          - commercial
      maven_version:
        description: 'Target Maven version (e.g. 3.9.16). When empty, the newest stable 3.x on Maven Central is used.'
        required: false
        type: string
        default: ''
      wrapper_version:
        description: 'Target org.apache.maven.wrapper:maven-wrapper version. When empty, the newest stable release is used.'
        required: false
        type: string
        default: ''
      regenerate:
        description: 'Regenerate the whole wrapper by running maven-wrapper-plugin (updates mvnw, mvnw.cmd and the JAR too). Uncheck to only edit maven-wrapper.properties.'
        required: false
        type: boolean
        default: true
      wrapper_type:
        description: 'Wrapper flavour to generate, when regenerate is checked. bin keeps the committed JAR (the shape almost every branch already has); only-script drops it.'
        required: false
        type: choice
        default: 'bin'
        options:
          - bin
          - only-script
          - script
      java_version:
        description: 'JDK used to run the wrapper plugin, when regenerate is checked.'
        required: false
        type: string
        default: '17'
      auto_merge:
        description: 'Merge existing wrapper PRs whose checks have all passed. Applies to this manual run only - the weekly scheduled run never merges.'
        required: false
        type: boolean
        default: true
      merge_method:
        description: 'How to merge a green wrapper PR.'
        required: false
        type: choice
        default: 'squash'
        options:
          - squash
          - merge
          - rebase
      check_only:
        description: 'Audit only. Reports every maven-wrapper.properties that Dependabot cannot read a wrapper version from, and fails if any exist. Changes nothing; every other input is ignored.'
        required: false
        type: boolean
        default: false
      dry_run:
        description: 'Dry run, if checked nothing is created, updated or merged, but you can see what would change'
        required: false
        type: boolean
        default: true
      token:
        description: 'GitHub token with contents:write and pull-requests:write on all target repos. Falls back to GH_ACTIONS_REPO_TOKEN.'
        required: false
        type: string
        default: ''

  # Mondays at ~7:00am US Eastern. As elsewhere in this repo, GitHub Actions cron is always
  # UTC with no notion of DST, so this is two month-selected entries - EDT (UTC-4) and EST
  # (UTC-5). Weekly rather than daily because a Maven release is a rare event and each run
  # can open PRs across ~79 branches; weekly is enough to keep the wrappers from drifting
  # far enough behind for Dependabot to start failing again.
  schedule:
    - cron: '0 11 * 3-10 1'      # ~7:00am EDT Monday, March-October
    - cron: '0 12 * 11,12,1,2 1' # ~7:00am EST Monday, November-February

permissions:
  contents: read

jobs:
  versions:
    name: Resolve Target Versions
    runs-on: ubuntu-latest
    outputs:
      maven: ${{ steps.resolve.outputs.maven }}
      maven-candidates: ${{ steps.resolve.outputs.maven-candidates }}
      wrapper: ${{ steps.resolve.outputs.wrapper }}
    steps:
      # For .github/scripts/version-cmp.js, the dotted-numeric comparator shared with
      # maven-wrapper-properties.js and update-antora-ui-bundle.yml.
      - name: Checkout
        uses: actions/checkout@v4

      - name: Resolve versions
        id: resolve
        env:
          MAVEN_INPUT: ${{ inputs.maven_version }}
          WRAPPER_INPUT: ${{ inputs.wrapper_version }}
          VERSION_CMP_LIB: ${{ github.workspace }}/.github/scripts/version-cmp.js
        run: |
          node - << 'JSEOF'
          const fs = require('fs');
          const { execFileSync } = require('child_process');
          const { cmp } = require(process.env.VERSION_CMP_LIB);

          const fetchMeta = url => {
            try {
              return execFileSync('curl', ['-sSL', '--max-time', '30', url], { encoding: 'utf8' });
            } catch (err) {
              console.log(`Could not fetch ${url}: ${err.message}`);
              return '';
            }
          };

          const versionsIn = xml =>
            [...xml.matchAll(/<version>([^<]+)<\/version>/g)].map(m => m[1]);

          // Maven Central's <latest> is currently a 4.0.0 release candidate, and Dependabot
          // itself stays on the stable line ("Filtered out 33 pre-release versions"), so the
          // target is the newest stable 3.x rather than whatever <latest> happens to say.
          // Every stable 3.x is kept, not just the newest: a branch Dependabot is told to hold
          // back (an ignore in dependabot.yml) moves to the newest one it has not ignored.
          let maven = (process.env.MAVEN_INPUT || '').trim();
          let candidates = maven ? [maven] : [];
          if (!maven) {
            const all = versionsIn(fetchMeta(
              'https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/maven-metadata.xml'));
            candidates = all.filter(v => /^3\.\d+\.\d+$/.test(v)).sort(cmp);
            maven = candidates[candidates.length - 1] || '';
          }

          let wrapper = (process.env.WRAPPER_INPUT || '').trim();
          if (!wrapper) {
            const all = versionsIn(fetchMeta(
              'https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/maven-metadata.xml'));
            const stable = all.filter(v => /^\d+\.\d+\.\d+$/.test(v)).sort(cmp);
            wrapper = stable[stable.length - 1] || '';
          }

          if (!maven || !wrapper) {
            console.log(`Could not resolve target versions (maven='${maven}', wrapper='${wrapper}').`);
            process.exit(1);
          }

          console.log(`Target Maven: ${maven}`);
          console.log(`Target maven-wrapper: ${wrapper}`);
          fs.appendFileSync(process.env.GITHUB_OUTPUT, `maven=${maven}\n`);
          fs.appendFileSync(process.env.GITHUB_OUTPUT, `maven-candidates=${JSON.stringify(candidates)}\n`);
          fs.appendFileSync(process.env.GITHUB_OUTPUT, `wrapper=${wrapper}\n`);
          JSEOF

  setup:
    name: Build Matrix
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.build-matrix.outputs.matrix }}
      count: ${{ steps.build-matrix.outputs.count }}
      excluded: ${{ steps.build-matrix.outputs.excluded }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build matrix
        id: build-matrix
        env:
          PROJECTS_FILTER: ${{ inputs.projects }}
          REPO_TYPE: ${{ inputs.repo_type || 'both' }}
          MATRIX_LIB: ${{ github.workspace }}/.github/scripts/project-branch-matrix.js
        run: |
          node - << 'JSEOF'
          const fs = require('fs');
          const { buildBranchMatrix } = require(process.env.MATRIX_LIB);

          const projects = JSON.parse(fs.readFileSync('config/projects.json', 'utf8'));

          // One entry per branch, not per repository - the wrapper is a file in the tree, so
          // every maintained branch has its own copy and its own PR. docs-build is
          // deliberately absent: it is not in projects.json, and its Dependabot config runs
          // the npm ecosystem rather than maven, so its wrapper is not part of this problem.
          // `-internal` branches are excluded by default (they are the in-flight development
          // line for the next train, so an unsolicited toolchain change there lands in the
          // middle of active work rather than on a settled branch) and reported separately so
          // the omission stays visible, rather than silently spending no runner on them.
          const { entries, excluded } = buildBranchMatrix(projects, {
            filter: process.env.PROJECTS_FILTER,
            repoType: process.env.REPO_TYPE,
          });

          console.log(`Repo/branch combinations to check: ${entries.length}`);
          for (const e of entries) console.log(`  ${e.repo}@${e.branch}`);
          console.log(`Excluded (-internal): ${excluded.length}`);
          for (const e of excluded) console.log(`  ${e}`);

          fs.appendFileSync(process.env.GITHUB_OUTPUT,
            `matrix=${JSON.stringify({ include: entries })}\n`);
          fs.appendFileSync(process.env.GITHUB_OUTPUT, `count=${entries.length}\n`);
          fs.appendFileSync(process.env.GITHUB_OUTPUT,
            `excluded=${JSON.stringify(excluded)}\n`);
          JSEOF

  update:
    name: "Wrapper — ${{ matrix.repo }}@${{ matrix.branch }}"
    needs: [versions, setup]
    if: needs.setup.outputs.count != '0'
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      max-parallel: 8
      matrix: ${{ fromJson(needs.setup.outputs.matrix) }}
    steps:
      # This repository, for the shared .github/scripts/*.js modules - maven-wrapper-properties.js
      # (the rules both this step and the regenerate step below edit properties files by),
      # gh-cli.js and git-pr-helpers.js (the generic gh/git-data-API mechanics). Checked out into
      # a subdirectory on purpose: a checkout at the workspace root would clean the
      # wrapper-*.json result file the steps here write there.
      - name: Checkout shared scripts
        uses: actions/checkout@v4
        with:
          path: ci-actions

      - name: Check and update wrapper
        id: update
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          WRAPPER_LIB: ${{ github.workspace }}/ci-actions/.github/scripts/maven-wrapper-properties.js
          GH_CLI_LIB: ${{ github.workspace }}/ci-actions/.github/scripts/gh-cli.js
          GIT_PR_LIB: ${{ github.workspace }}/ci-actions/.github/scripts/git-pr-helpers.js
          DEPENDABOT_IGNORE_LIB: ${{ github.workspace }}/ci-actions/.github/scripts/dependabot-ignore.js
          REPO: ${{ matrix.repo }}
          BRANCH: ${{ matrix.branch }}
          PROJECT: ${{ matrix.project }}
          TYPE: ${{ matrix.type }}
          MAVEN_VERSION: ${{ needs.versions.outputs.maven }}
          MAVEN_CANDIDATES: ${{ needs.versions.outputs.maven-candidates }}
          WRAPPER_VERSION: ${{ needs.versions.outputs.wrapper }}
          # A scheduled run has no inputs, so `inputs.dry_run != false` would be true and the
          # weekly job would never actually do anything. Schedule therefore acts, while a
          # manual dispatch still defaults to a dry run so a human can look first.
          DRY_RUN: ${{ github.event_name == 'schedule' && 'false' || (inputs.dry_run != false) }}
          REGENERATE: ${{ (github.event_name == 'schedule' || inputs.regenerate == true) }}
          # Audit only. A scheduled run never audits: it fixes, which is strictly better.
          CHECK_ONLY: ${{ github.event_name != 'schedule' && inputs.check_only == true }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');

          // The generic gh-CLI and git-data-API/PR mechanics - shared with
          // update-antora-ui-bundle.yml, which opens bot PRs the same way.
          const { gh, ghRetry } = require(process.env.GH_CLI_LIB);
          const PR = require(process.env.GIT_PR_LIB);
          const { execFileSync } = require('child_process');

          // The ignore rules in the repository's dependabot.yml, so a branch Dependabot has been
          // told to hold on an older Maven is held here too.
          const { pickMavenTarget } = require(process.env.DEPENDABOT_IGNORE_LIB);

          // Same rules the regenerate step applies against a real checkout - see the header of that
          // file for why they live outside this workflow.
          const W = require(process.env.WRAPPER_LIB);

          const REPO = process.env.REPO;
          const BRANCH = process.env.BRANCH;
          // The newest stable Maven. `MAVEN`, below, is what *this branch* moves to, which is
          // lower when dependabot.yml ignores the newest for it.
          const NEWEST_MAVEN = process.env.MAVEN_VERSION;
          let MAVEN = NEWEST_MAVEN;
          // In regenerate mode this step only decides *whether* work is needed and hands the
          // branch name to the steps below - the files are produced by the wrapper plugin
          // against a real checkout, which the contents API cannot do.
          const REGENERATE = process.env.REGENERATE === 'true';
          const WRAPPER = process.env.WRAPPER_VERSION;
          const DRY = process.env.DRY_RUN !== 'false';
          // Audit mode: report what Dependabot would fail to parse, and write nothing at all.
          const CHECK = process.env.CHECK_ONLY === 'true';

          const safe = `${REPO}@${BRANCH}`.replace(/[/@]/g, '-');
          const finish = (status, detail, extra = {}) => {
            const result = { project: process.env.PROJECT, repo: REPO, type: process.env.TYPE,
              branch: BRANCH, status, detail, dryRun: DRY, checkOnly: CHECK, ...extra };
            fs.writeFileSync(`wrapper-${safe}.json`, JSON.stringify(result, null, 2));
            fs.appendFileSync(process.env.GITHUB_OUTPUT, `safe-name=${safe}\n`);
            // Only a PR that is already open AND already at the target is a merge
            // candidate. One just opened, or just moved up, has no finished CI yet.
            if (status === 'pr-open' && extra.prNumber) {
              fs.appendFileSync(process.env.GITHUB_OUTPUT, `merge-candidate=${extra.prNumber}\n`);
            }
            console.log(`${REPO}@${BRANCH}: ${status}${detail ? ` - ${detail}` : ''}`);
            process.exit(0);
          };

          // Encoded for query strings; left raw inside a path, where GitHub accepts the
          // slashes a branch name may contain.
          const enc = encodeURIComponent(BRANCH);

          // ── Find every wrapper Dependabot will read ─────────────────────────────────────
          // Not just the root one. Dependabot's Maven file fetcher looks for a wrapper in the
          // directory of every pom it fetches - the root plus each <module> - and its parser raises
          // on any it cannot read a version out of, which aborts the whole repository's update job.
          // A root wrapper in perfect shape therefore buys nothing while a submodule still carries
          // the single-line 2018 file. One recursive tree listing finds them all in one request.
          const tree = ghRetry(['api', `repos/${REPO}/git/trees/${enc}?recursive=1`]);
          if (!tree.ok) {
            const missing = /404|Not Found/i.test(tree.err);
            finish(missing ? 'no-wrapper' : 'error',
              missing ? 'branch not found' : `could not list the tree: ${tree.err}`);
          }
          const treeJson = JSON.parse(tree.out);
          const paths = (treeJson.tree || []).map(e => e.path);
          const pathSet = new Set(paths);

          // GitHub caps a recursive tree listing and says so rather than lying about it. Falling
          // back to the root wrapper keeps the run useful, and the flag is carried into the summary
          // so "no module wrappers found" is never confused with "modules were not looked at".
          const truncated = treeJson.truncated === true;
          let dirs = W.wrapperDirs(paths);
          if (truncated) dirs = dirs.filter(d => d === '.');

          if (!dirs.length) {
            finish('no-wrapper', 'no maven-wrapper.properties in any directory with a pom.xml',
              { truncated });
          }

          const files = [];
          for (const dir of dirs) {
            const path = W.propsPath(dir);
            const got = PR.readFileAt(REPO, path, enc);
            if (!got) finish('error', `could not read ${path}`);
            files.push({ dir, path, sha: got.sha, text: got.text });
          }

          // ── Audit mode ──────────────────────────────────────────────────────────────────
          // Answers one question: would Dependabot's parser survive this branch? The scripts are
          // only fetched for files that need them - i.e. those with neither wrapperVersion nor
          // wrapperUrl - so a healthy branch costs no extra requests.
          if (CHECK) {
            const broken = [];
            for (const f of files) {
              if (W.dependabotWrapperVersion(f.text)) continue;
              const present = W.scriptPaths(f.dir).filter(p => pathSet.has(p));
              const scripts = present.map(p => PR.readFileAt(REPO, p, enc)).filter(Boolean).map(s => s.text);
              if (W.dependabotWrapperVersion(f.text, scripts)) continue;
              broken.push({ path: f.path, reason: present.length
                ? `no wrapperVersion or wrapperUrl, and no version banner in ${present.join(', ')}`
                : 'no wrapperVersion or wrapperUrl, and no mvnw script to read one from' });
            }
            const extra = { wrappers: files.length, broken, truncated };
            if (broken.length) {
              finish('check-broken',
                `${broken.length} of ${files.length} wrapper file(s) would break Dependabot`, extra);
            }
            finish('check-ok', `all ${files.length} wrapper file(s) readable by Dependabot`, extra);
          }

          // ── Which Maven does dependabot.yml let this branch have? ───────────────────────
          // Read from the default branch (no ref), which is where Dependabot reads it from - a
          // `target-branch` entry there is what pins an older branch. Any failure to read it
          // means no restriction: the workflow's job is to keep wrappers current, so it fails
          // open rather than stalling a branch on a flaky API call or an unparseable file.
          const fetchRaw = path => {
            const args = ['api', '-H', 'Accept: application/vnd.github.raw+json',
              `repos/${REPO}/contents/${path}`];
            let r = gh(args);
            if (!r.ok && !/404|Not Found/i.test(r.err)) r = ghRetry(args);
            return r;
          };
          const loadDependabotConfig = () => {
            for (const path of ['.github/dependabot.yml', '.github/dependabot.yaml']) {
              const r = fetchRaw(path);
              if (r.ok) {
                try {
                  return JSON.parse(execFileSync('yq', ['-o=json', '.'],
                    { input: r.out, encoding: 'utf8', maxBuffer: 1 << 26 }));
                } catch (err) {
                  console.log(`Could not parse ${path}: ${(err.message || '').split('\n')[0]}`);
                  return null;
                }
              }
              if (!/404|Not Found/i.test(r.err)) {
                console.log(`Could not read ${path}: ${r.err}`);
                return null;
              }
            }
            return null;
          };

          let candidates = [];
          try { candidates = JSON.parse(process.env.MAVEN_CANDIDATES || '[]'); } catch (e) { /* none */ }
          let heldBack = null;
          const dependabotConfig = candidates.length ? loadDependabotConfig() : null;
          if (dependabotConfig) {
            const def = ghRetry(['api', `repos/${REPO}`, '--jq', '.default_branch']);
            const pick = pickMavenTarget(dependabotConfig, {
              branch: BRANCH,
              defaultBranch: def.ok ? def.out.trim() : '',
              current: W.currentMaven((files.find(f => f.dir === '.') || files[0]).text),
              candidates,
              warn: msg => console.log(`dependabot.yml: ${msg}`),
            });
            if (pick.skipped.length) {
              const why = `${pick.skipped.map(s => s.version).join(', ')} ignored by ${pick.skipped[0].reason}`;
              if (!pick.target) {
                finish('ignored-by-dependabot', why,
                  { target: null, newest: NEWEST_MAVEN, truncated });
              }
              heldBack = { versions: pick.skipped.map(s => s.version), why };
              console.log(`${REPO}@${BRANCH}: Maven ${pick.target} instead of ${NEWEST_MAVEN} - ${why}`);
            }
            MAVEN = pick.target;
          }
          fs.appendFileSync(process.env.GITHUB_OUTPUT, `maven-target=${MAVEN}\n`);

          // ── Work out what each file should become ───────────────────────────────────────
          // Per file, not per branch: a repository can be current at the root and years behind in a
          // submodule, which is exactly the state the estate was found in.
          const plan = list => list.map(f => {
            const current = W.currentMaven(f.text);
            // Never walk a file backwards. A file already past the target keeps its own Maven
            // version and is still eligible for the wrapper-key repair, which is what Dependabot
            // actually needs - the two concerns are independent.
            const ahead = current !== null && W.cmp(current, MAVEN) > 0;
            const updated = W.rewrite(f.text, { maven: ahead ? current : MAVEN, wrapper: WRAPPER });
            return { ...f, current, ahead, updated, changed: updated !== f.text };
          });

          const planned = plan(files);
          const changed = planned.filter(f => f.changed);
          const rootFile = planned.find(f => f.dir === '.') || planned[0];
          const current = rootFile.current;
          const extras = { current, target: MAVEN, newest: NEWEST_MAVEN, heldBack, wrappers: planned.length,
            changedPaths: changed.map(f => f.path), truncated };

          // How the work reads in the summary and the PR title/body: one file names itself, several
          // are counted, because a nine-module repository would otherwise fill the table.
          const describe = list => list.length === 1
            ? (list[0].dir === '.' ? 'the root wrapper' : `\`${list[0].path}\``)
            : `${list.length} wrapper files`;

          // Only quote an arrow when the root wrapper is actually one of the files moving.
          // A repository current at the root and years behind in nine submodules would
          // otherwise report "Maven 3.9.16 -> 3.9.16", which reads like a no-op.
          const versionPhrase = list => {
            const root = list.find(f => f.dir === '.');
            return root ? `Maven ${root.current} -> ${MAVEN}` : `Maven ${MAVEN}`;
          };

          if (!changed.length) {
            if (planned.every(f => f.current === null)) {
              finish('unparsed', 'could not read a Maven version from any distributionUrl', extras);
            }
            if (planned.some(f => f.ahead)) {
              finish('ahead', `Maven ${current} is newer than the target ${MAVEN}`, extras);
            }
            if (heldBack) {
              finish('ignored-by-dependabot',
                `Maven ${current} is the newest release allowed for this branch (latest is ${NEWEST_MAVEN}); ` +
                heldBack.why, extras);
            }
            finish('up-to-date',
              `Maven ${current}` + (planned.length > 1 ? ` (${planned.length} wrapper files)` : ''),
              extras);
          }

          // ── Is there already a PR for this branch? ──────────────────────────────────────
          // The head name includes the base branch. Without it every branch in a repo would
          // share one head ref, so the first matrix job would create it and the rest would
          // collide - and with several maintained branches per repo, most would silently be
          // skipped. Slashes are flattened so a branch like release/1.2.x stays one segment.
          const slug = BRANCH.replace(/\//g, '-');
          const PREFIX = 'maven-wrapper-update/';
          const head = `${PREFIX}${slug}-${MAVEN}`;

          const authorName = 'spring-builds';
          const authorEmail = 'spring-builds@users.noreply.github.com';
          // Spring Cloud repositories run a required DCO check, so the commit needs a
          // Signed-off-by trailer whose address matches the commit author. Both are set
          // explicitly here rather than left to the token's default identity.
          const message = `Update Maven wrapper to ${MAVEN}\n\n` +
            `Signed-off-by: ${authorName} <${authorEmail}>`;
          const author = { name: authorName, email: authorEmail };

          // One commit for N files, via git-pr-helpers.js's tree/commit/ref-move sequence -
          // the contents API writes a single file per call and therefore makes a separate
          // commit for each, so a branch touching nine module wrappers would arrive as nine
          // commits with the same message.
          const commitFiles = (ref, list) => PR.commitFilesToRef(REPO, ref,
            list.map(f => ({ path: f.path, content: f.updated })), message, author);

          // Matched by prefix and base rather than by exact head, so a PR opened for an
          // earlier target version is found too. Otherwise each new Maven release would
          // stack another PR on top of the last one, all editing the same file.
          const findPr = PR.findOpenPrByHeadPrefix(REPO, BRANCH, `${PREFIX}${slug}-`);
          if (!findPr.ok) finish('error', `could not list pull requests: ${findPr.err}`);

          if (findPr.pr) {
            const pr = findPr.pr;
            // Read the PR's own head branch: it may already be at the target (nothing to
            // do), or behind it (a newer Maven has shipped since it was opened). The file list
            // comes from the base branch, so a wrapper added to the base after the PR was opened is
            // picked up too; one that has since been deleted is skipped rather than failing the job.
            const headRef = encodeURIComponent(pr.head.ref);
            const onHead = [];
            for (const f of planned) {
              const got = PR.readFileAt(REPO, f.path, headRef);
              if (got) onHead.push({ ...f, sha: got.sha, text: got.text });
            }
            const headPlan = plan(onHead);
            const headChanged = headPlan.filter(f => f.changed);

            // A PR opened before the ignore existed (for the version now ignored) is already past
            // this branch's target. It is left alone - closing it is a human decision - but it must
            // not read as current, nor be offered for auto-merge.
            if (heldBack && headPlan.some(f => f.ahead)) {
              finish('ignored-by-dependabot',
                `#${pr.number} is open for a Maven the branch is held below (${heldBack.why}) - close it`,
                { ...extras, prUrl: pr.html_url });
            }
            if (!headChanged.length) {
              finish('pr-open', `#${pr.number} already open for ${MAVEN}`,
                { ...extras, prUrl: pr.html_url, prNumber: pr.number });
            }
            if (DRY) {
              finish('would-update-pr',
                `#${pr.number} would be moved up to ${MAVEN} (${describe(headChanged)})` +
                (REGENERATE ? ' (regenerated)' : ''),
                { ...extras, prUrl: pr.html_url });
            }
            if (REGENERATE) {
              fs.appendFileSync(process.env.GITHUB_OUTPUT, `regenerate-head=${pr.head.ref}\n`);
              fs.appendFileSync(process.env.GITHUB_OUTPUT, `regenerate-pr=${pr.number}\n`);
              fs.appendFileSync(process.env.GITHUB_OUTPUT, `regenerate-current=${current}\n`);
              finish('regenerating', `#${pr.number} on ${pr.head.ref}`,
                { ...extras, prUrl: pr.html_url });
            }
            // Commit onto the existing PR's branch so it updates in place - one wrapper PR
            // per branch, always at the current target, rather than a growing stack.
            const bump = commitFiles(pr.head.ref, headChanged);
            if (!bump.ok) finish('error', `could not update #${pr.number}: ${bump.err}`);
            finish('pr-updated', `#${pr.number} moved up to ${MAVEN} (${describe(headChanged)})`,
              { ...extras, prUrl: pr.html_url, prNumber: pr.number });
          }

          if (DRY) {
            finish('would-open', `${versionPhrase(changed)}, ${describe(changed)}` +
              (REGENERATE ? ' (regenerated)' : ''), extras);
          }

          // Regenerate mode stops here: the branch is created by `git push` from the real
          // checkout below, not through the git refs API.
          if (REGENERATE) {
            fs.appendFileSync(process.env.GITHUB_OUTPUT, `regenerate-head=${head}\n`);
            fs.appendFileSync(process.env.GITHUB_OUTPUT, `regenerate-current=${current}\n`);
            finish('regenerating', `${current} -> ${MAVEN} on ${head}`, extras);
          }

          // ── Create the branch ───────────────────────────────────────────────────────────
          const madeRef = PR.createBranch(REPO, head, BRANCH);
          if (!madeRef.ok) finish('error', madeRef.err);
          // An existing branch with no open PR means a previous PR was closed unmerged.
          // Leaving it alone is deliberate - reopening it would re-litigate that decision.
          if (madeRef.alreadyExists) {
            finish('branch-exists', `${head} exists but no PR is open - left alone`, extras);
          }

          // ── Commit the change ───────────────────────────────────────────────────────────
          const put = commitFiles(head, changed);
          if (!put.ok) finish('error', `could not commit: ${put.err}`);

          // ── Open the PR ─────────────────────────────────────────────────────────────────
          const rootChanged = changed.find(f => f.dir === '.');
          const moduleChanged = changed.filter(f => f.dir !== '.');

          const prBody = [
            rootChanged
              ? `Updates the Maven wrapper on \`${BRANCH}\` from **${rootChanged.current}** to ` +
                `**${MAVEN}**, and \`maven-wrapper\` to **${WRAPPER}**.`
              : `Updates the module Maven wrappers on \`${BRANCH}\` to Maven **${MAVEN}** and ` +
                `\`maven-wrapper\` **${WRAPPER}**.`,
            '',
            `Files changed (${changed.length}):`,
            '',
            ...changed.map(f => `- \`${f.path}\`` +
              (f.current ? ` — Maven ${f.current} → ${f.ahead ? f.current : MAVEN}` : '') +
              (W.dependabotWrapperVersion(f.text) ? '' : ' — **adds the missing `wrapperVersion`**')),
            '',
            'Opened automatically by [update-maven-wrapper.yml](https://github.com/spring-cloud/spring-cloud-github-actions/blob/main/.github/workflows/update-maven-wrapper.yml).',
            '',
            'Keeping the wrapper current stops Dependabot from trying to update it itself, ' +
            'which currently fails - it shells out to `mvn wrapper:wrapper`, which cannot ' +
            'resolve an unpublished SNAPSHOT parent POM, and it cannot parse the older ' +
            'wrapper formats.',
          ];
          if (heldBack) {
            prBody.push('',
              `Maven ${heldBack.versions.join(', ')} is not used for \`${BRANCH}\`: ${heldBack.why}.`);
          }
          if (moduleChanged.length) {
            prBody.push('',
              'Module wrappers are included because Dependabot reads the wrapper in the directory ' +
              'of *every* pom it fetches, and a single unreadable one aborts the whole ' +
              'repository\'s update job - not merely the wrapper update.');
          }

          const opened = PR.openPr(REPO, {
            title: `Update Maven wrapper to ${MAVEN}`,
            head, base: BRANCH, body: prBody.join('\n'),
          });
          if (!opened.ok) finish('error', opened.err);

          finish('pr-opened', `#${opened.pr.number}: ${versionPhrase(changed)} (${describe(changed)})`,
            { ...extras, prUrl: opened.pr.html_url, prNumber: opened.pr.number });
          JSEOF

      # ── Regenerate mode ─────────────────────────────────────────────────────────────
      # Everything below runs only when `regenerate` is set and the step above decided this
      # branch needs work. Regenerating means running maven-wrapper-plugin against a real
      # checkout, which rewrites mvnw, mvnw.cmd and the JAR as well as the properties -
      # more than the contents API can express, hence the checkout, JDK and git push.
      # This repository is already checked out into ci-actions by the first step.
      - name: Checkout target branch
        if: (github.event_name == 'schedule' || inputs.regenerate == true) && steps.update.outputs.regenerate-head != ''
        uses: actions/checkout@v4
        with:
          repository: ${{ matrix.repo }}
          ref: ${{ matrix.branch }}
          path: target
          token: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          fetch-depth: 0

      - name: Set up JDK
        if: (github.event_name == 'schedule' || inputs.regenerate == true) && steps.update.outputs.regenerate-head != ''
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: ${{ inputs.java_version || '17' }}

      # .settings.xml resolves ${env.COMMERCIAL_ARTIFACTORY_USERNAME} and friends, so the
      # secrets have to reach Maven as environment variables. This is the repo's own action
      # for that, which also falls back to the read-only credentials when the read/write
      # pair is unavailable - the case that silently produced empty credentials before.
      # It writes to $GITHUB_ENV, so it must run in a step of its own, before Maven.
      - name: Set commercial credentials
        if: (github.event_name == 'schedule' || inputs.regenerate == true) && steps.update.outputs.regenerate-head != ''
        env:
          USERNAME: ${{ secrets.COMMERCIAL_ARTIFACTORY_USERNAME }}
          PASSWORD: ${{ secrets.COMMERCIAL_ARTIFACTORY_PASSWORD }}
          RO_USERNAME: ${{ secrets.ARTIFACTORY_USERNAME }}
          RO_PASSWORD: ${{ secrets.ARTIFACTORY_PASSWORD }}
        uses: ./ci-actions/.github/actions/set-commercial-creds-env-vars

      - name: Regenerate wrapper and open PR
        if: (github.event_name == 'schedule' || inputs.regenerate == true) && steps.update.outputs.regenerate-head != ''
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          REPO: ${{ matrix.repo }}
          BRANCH: ${{ matrix.branch }}
          HEAD_REF: ${{ steps.update.outputs.regenerate-head }}
          EXISTING_PR: ${{ steps.update.outputs.regenerate-pr }}
          CURRENT: ${{ steps.update.outputs.regenerate-current }}
          SAFE_NAME: ${{ steps.update.outputs.safe-name }}
          # Per branch: lower than the newest when dependabot.yml ignores the newest for it.
          MAVEN_VERSION: ${{ steps.update.outputs.maven-target || needs.versions.outputs.maven }}
          WRAPPER_VERSION: ${{ needs.versions.outputs.wrapper }}
          WRAPPER_TYPE: ${{ inputs.wrapper_type || 'bin' }}
          WRAPPER_LIB: ${{ github.workspace }}/ci-actions/.github/scripts/maven-wrapper-properties.js
          # COMMERCIAL_ARTIFACTORY_USERNAME/PASSWORD deliberately absent: they arrive from
          # $GITHUB_ENV via the step above, and a step-level env: here would override it
          # with the raw secret, losing the read-only fallback. CI_DEPLOY_* is what the
          # repo.spring.io server entry in .settings.xml resolves.
          CI_DEPLOY_USERNAME: ${{ secrets.ARTIFACTORY_USERNAME }}
          CI_DEPLOY_PASSWORD: ${{ secrets.ARTIFACTORY_PASSWORD }}
        run: |
          set -uo pipefail

          RESULT="wrapper-${SAFE_NAME}.json"
          record() {
            node -e '
              const fs = require("fs");
              const [file, status, detail, prUrl] = process.argv.slice(1);
              let r = {};
              try { r = JSON.parse(fs.readFileSync(file, "utf8")); } catch (e) {}
              fs.writeFileSync(file, JSON.stringify(
                { ...r, status, detail, ...(prUrl ? { prUrl } : {}) }, null, 2));
            ' "$RESULT" "$1" "$2" "${3:-}"
            echo "${REPO}@${BRANCH}: $1 - $2"
          }

          cd target

          # The branch's own .settings.xml is the only file used - it is what that branch's
          # CI actually builds with, it is maintained per branch, and it is the one that
          # names the OSS snapshot repository. There is no fallback: a branch without it
          # would resolve against Maven Central alone and fail on its own SNAPSHOT parent,
          # so saying so plainly beats guessing with someone else's settings.
          if [ ! -f .settings.xml ]; then
            cd ..; record "regenerate-failed" "no .settings.xml on this branch"; exit 0
          fi

          # Report which ${env.*} placeholders this branch's .settings.xml depends on and
          # whether each one actually arrived. An empty credential otherwise surfaces only
          # as a 401 from Artifactory, or as a resolution failure that reads like a missing
          # artifact - neither of which points at the real cause. Names only; never values.
          echo "Credentials referenced by .settings.xml:"
          MISSING=""
          for VAR in $(grep -oE '\$\{env\.[A-Za-z0-9_]+\}' .settings.xml \
                        | sed -E 's/^\$\{env\.([A-Za-z0-9_]+)\}$/\1/' | sort -u); do
            if [ -n "${!VAR:-}" ]; then
              echo "  ${VAR}: set"
            else
              echo "  ${VAR}: EMPTY"
              MISSING="${MISSING} ${VAR}"
            fi
          done
          [ -n "${MISSING}" ] && echo "Warning: empty credentials:${MISSING}"

          # The runner's own mvn, deliberately not ./mvnw: using the wrapper to regenerate
          # the wrapper is circular - the old wrapper would have to boot the old Maven
          # before it could be replaced, which on the oldest branches means Maven 3.6.3,
          # exactly the floor maven-wrapper-plugin 3.x requires. The runner's Maven is
          # current and has no such constraint. Only the settings file and profile need to
          # match what CI does; the Maven that writes the files does not.
          #
          # -Pspring matters as much as the settings file: the repositories are declared
          # inside a `spring` profile, so without activating it the snapshot repositories
          # are not in play at all and the parent POM cannot resolve.
          #
          # -N is not just a speed-up and must not be dropped. wrapper:wrapper is not an
          # aggregator goal, so on a full reactor it executes once per module and writes a
          # brand-new mvnw, mvnw.cmd and .mvn/wrapper into every submodule - including the
          # ~180 across the estate that have never had one. Module wrappers that DO exist
          # are handled by the textual edit below instead.
          # Piped through tee, not redirected to a file: Maven's output has to reach the job
          # log, otherwise a failure here is undiagnosable and only the one-line summary
          # below survives. pipefail (set above) is what keeps mvn's exit status visible
          # through the pipe.
          echo "Running maven-wrapper-plugin ${WRAPPER_VERSION} for Maven ${MAVEN_VERSION}..."
          if ! mvn -B -N -s .settings.xml -Pspring \
                "org.apache.maven.plugins:maven-wrapper-plugin:${WRAPPER_VERSION}:wrapper" \
                "-Dmaven=${MAVEN_VERSION}" "-Dtype=${WRAPPER_TYPE}" 2>&1 | tee ../mvn.log; then
            cd ..

            echo "::group::Maven failure detail"
            grep -E "^\[(ERROR|WARNING)\]" mvn.log | tail -40 || tail -40 mvn.log
            echo "::endgroup::"

            # Pick the first line that actually says something. Maven leads with
            # "Some problems were encountered while processing the POMs:" and trails with
            # Help links, none of which identify the problem - matching those first is how
            # the previous run ended up reporting a header and nothing else.
            REASON=$(grep -oE "(Non-resolvable (parent|import) POM|Could not find artifact|Could not resolve dependencies|Could not transfer artifact|Failed to execute goal|Unauthorized|status code: 40[0-9])[^\"]*" mvn.log | head -1)
            if [ -z "$REASON" ]; then
              REASON=$(grep -E "^\[ERROR\]" mvn.log \
                | grep -vE "Some problems were encountered|To see the full stack|Re-run Maven|For more information|\[Help|^\[ERROR\][[:space:]]*$" \
                | head -1)
            fi
            [ -z "$REASON" ] && REASON="see the Maven failure detail in the job log"
            REASON=$(echo "$REASON" | cut -c1-300)

            record "regenerate-failed" "${REASON}"
            exit 0
          fi
          cd ..

          cd target
          # Bring up the wrapper of every *module* that has one. The plugin above only
          # touched the root (-N), but Dependabot reads the wrapper in the directory of
          # every pom it fetches and raises on any it cannot read a version out of, which
          # aborts that repository's whole update job. Same shared rules the properties-only
          # path applies, so the two modes cannot produce different files.
          echo "Updating module wrapper properties..."
          if ! git ls-files | node -e '
            const fs = require("fs");
            const W = require(process.env.WRAPPER_LIB);
            const paths = fs.readFileSync(0, "utf8").split("\n").filter(Boolean);
            const maven = process.env.MAVEN_VERSION;
            const wrapper = process.env.WRAPPER_VERSION;
            let n = 0;
            for (const dir of W.wrapperDirs(paths)) {
              if (dir === ".") continue;
              const file = W.propsPath(dir);
              const before = fs.readFileSync(file, "utf8");
              const current = W.currentMaven(before);
              // Never walk a file backwards; the wrapper-key repair still applies.
              const target = current !== null && W.cmp(current, maven) > 0 ? current : maven;
              const after = W.rewrite(before, { maven: target, wrapper });
              if (after === before) continue;
              fs.writeFileSync(file, after);
              console.log(`  ${file}: Maven ${current || "?"} -> ${target}`);
              n++;
            }
            console.log(`${n} module wrapper file(s) updated.`);
          '; then
            cd ..
            record "regenerate-failed" "could not update the module wrapper properties"
            exit 0
          fi

          if [ -z "$(git status --porcelain)" ]; then
            cd ..
            record "up-to-date" "wrapper plugin and module properties produced no changes"
            exit 0
          fi
          echo "Changed files:"; git status --porcelain

          # Spring Cloud repositories run a required DCO check, so the commit is signed off
          # and the author matches that trailer.
          git config user.name  "spring-builds"
          git config user.email "spring-builds@users.noreply.github.com"

          # The branch is always cut fresh from the base branch and force-pushed, rather
          # than the existing PR branch being fetched and added to. The generated files were
          # produced against the base checkout, so committing them onto a divergent branch
          # would mix two states; and the PR branch only ever holds our own generated
          # commit, so replacing it wholesale is exactly the intent. --force rather than
          # --force-with-lease because the remote branch was never fetched, which would make
          # a lease check fail on stale info rather than protect anything.
          git checkout -b "$HEAD_REF"
          git add -A
          if ! git commit -s -m "Update Maven wrapper to ${MAVEN_VERSION}"; then
            cd ..; record "error" "nothing to commit after regeneration"; exit 0
          fi

          if ! git push --force origin "$HEAD_REF"; then
            cd ..; record "error" "could not push ${HEAD_REF}"; exit 0
          fi
          cd ..

          if [ -n "${EXISTING_PR}" ]; then
            URL=$(gh pr view "${EXISTING_PR}" --repo "${REPO}" --json url --jq .url 2>/dev/null)
            record "pr-updated" "#${EXISTING_PR} regenerated at ${MAVEN_VERSION}" "$URL"
            exit 0
          fi

          BODY=$(printf '%s\n' \
            "Regenerates the Maven wrapper on \`${BRANCH}\` from **${CURRENT}** to **${MAVEN_VERSION}** using maven-wrapper-plugin ${WRAPPER_VERSION} (\`${WRAPPER_TYPE}\`)." \
            "" \
            "Unlike the properties-only update, this also rewrites \`mvnw\`, \`mvnw.cmd\` and the wrapper JAR, so the diff is larger. **Merge only once CI is green.**" \
            "" \
            "Opened automatically by [update-maven-wrapper.yml](https://github.com/spring-cloud/spring-cloud-github-actions/blob/main/.github/workflows/update-maven-wrapper.yml).")

          URL=$(gh pr create --repo "${REPO}" --base "${BRANCH}" --head "${HEAD_REF}" \
            --title "Update Maven wrapper to ${MAVEN_VERSION}" --body "${BODY}" 2>&1) \
            || { record "error" "could not open PR: ${URL}"; exit 0; }

          record "pr-opened" "${CURRENT} -> ${MAVEN_VERSION} (regenerated)" "$URL"

      # Only runs when the previous step found a PR that is open and already at the target
      # version - i.e. one whose CI has had a chance to finish. A PR opened or moved up in
      # this same run is deliberately not a candidate: its checks have not started yet.
      #
      # Auto-merge is switched off for the weekly scheduled run: these are real Maven
      # upgrades, so the schedule opens and refreshes PRs and a human decides when they
      # land. A manual dispatch still honours the auto_merge input, so merging green PRs in
      # bulk is one deliberate click away. To let the schedule merge unattended later,
      # delete the `github.event_name != 'schedule'` clause below.
      - name: Merge PR if all checks pass
        if: >-
          always()
          && github.event_name != 'schedule'
          && inputs.auto_merge != false
          && steps.update.outputs.merge-candidate != ''
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          REPO: ${{ matrix.repo }}
          BRANCH: ${{ matrix.branch }}
          PR_NUMBER: ${{ steps.update.outputs.merge-candidate }}
          SAFE_NAME: ${{ steps.update.outputs.safe-name }}
          MERGE_METHOD: ${{ inputs.merge_method || 'squash' }}
          DRY_RUN: ${{ github.event_name == 'schedule' && 'false' || (inputs.dry_run != false) }}
          MERGE_LIB: ${{ github.workspace }}/ci-actions/.github/scripts/merge-if-green.js
        run: |
          node - << 'JSEOF'
          const fs = require('fs');
          const { mergeIfGreen } = require(process.env.MERGE_LIB);

          const REPO = process.env.REPO;
          const PR = process.env.PR_NUMBER;
          const DRY = process.env.DRY_RUN !== 'false';
          const METHOD = process.env.MERGE_METHOD || 'squash';
          const FILE = `wrapper-${process.env.SAFE_NAME}.json`;

          const { status, detail } = mergeIfGreen({ repo: REPO, pr: PR, method: METHOD, dryRun: DRY });

          // Merge outcome is folded back into the result the previous step wrote, so the
          // summary reports one row per repo/branch rather than two disjoint views.
          let result = {};
          try { result = JSON.parse(fs.readFileSync(FILE, 'utf8')); } catch (_) { /* first write */ }
          fs.writeFileSync(FILE, JSON.stringify(
            { ...result, mergeStatus: status, mergeDetail: detail }, null, 2));
          console.log(`${REPO} #${PR}: ${status}${detail ? ` - ${detail}` : ''}`);
          JSEOF

      # Guarded on safe-name: if the script died before writing its result, the artifact
      # name would be a bare "wrapper-", which GitHub rejects and which would turn a
      # reporting gap into a job failure.
      - name: Upload result
        if: always() && steps.update.outputs.safe-name != ''
        uses: actions/upload-artifact@v4
        with:
          name: wrapper-${{ steps.update.outputs.safe-name }}
          path: wrapper-${{ steps.update.outputs.safe-name }}.json
          if-no-files-found: ignore

  summary:
    name: Summary
    needs: [versions, setup, update]
    runs-on: ubuntu-latest
    if: always()
    steps:
      - name: Download results
        uses: actions/download-artifact@v4
        with:
          pattern: wrapper-*
          merge-multiple: true
          path: results

      - name: Write summary
        env:
          MAVEN_VERSION: ${{ needs.versions.outputs.maven }}
          WRAPPER_VERSION: ${{ needs.versions.outputs.wrapper }}
          EVENT_NAME: ${{ github.event_name }}
          EXCLUDED: ${{ needs.setup.outputs.excluded }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');

          let results = [];
          try {
            results = fs.readdirSync('results')
              .filter(f => f.endsWith('.json'))
              .map(f => JSON.parse(fs.readFileSync(`results/${f}`, 'utf8')))
              .sort((a, b) => a.repo.localeCompare(b.repo) || a.branch.localeCompare(b.branch));
          } catch (err) {
            console.log('No results to summarize.');
          }

          const dry = results.some(r => r.dryRun);
          const check = results.some(r => r.checkOnly);
          const of = s => results.filter(r => r.status === s);

          const md = [`## ${check ? 'Check' : 'Update'} Maven Wrapper`, ''];

          // Named rather than merely counted: an omission nobody can see is one nobody can
          // question, and these are branches a reader would otherwise assume were covered.
          let excluded = [];
          try { excluded = JSON.parse(process.env.EXCLUDED || '[]'); } catch (_) { /* absent */ }
          const renderExcluded = () => {
            if (!excluded.length) return;
            md.push('', `### Skipped — \`-internal\` branches (${excluded.length})`, '');
            md.push('Left alone deliberately: these are the in-flight development line for ' +
              'the next train, so the wrapper is not changed under active work.', '');
            for (const e of excluded) md.push(`- \`${e}\``);
          };

          // A truncated tree listing means module wrappers were never looked at on that branch, so
          // a clean result there is not evidence of anything. Called out wherever it happens.
          const renderTruncated = () => {
            const cut = results.filter(r => r.truncated);
            if (!cut.length) return;
            md.push('', `> **${cut.length} branch(es) had a truncated tree listing** — only the root ` +
              'wrapper was inspected there: ' + cut.map(r => `\`${r.repo}@${r.branch}\``).join(', '), '');
          };

          const write = failed => {
            renderTruncated();
            renderExcluded();
            fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, md.join('\n') + '\n');
            console.log(md.join('\n'));
            // Always exits: this script runs from stdin, where a top-level `return` is a
            // syntax error, so every branch below ends by calling write().
            process.exit(failed ? 1 : 0);
          };

          // ── Audit mode ────────────────────────────────────────────────────────────────────
          // A separate report, not a column bolted onto the update one: the question it answers is
          // not "how far behind is this branch" but "will Dependabot survive it", and the answer has
          // to be loud. The job fails when anything is broken so the workflow works as a canary -
          // scheduled from elsewhere, or run by hand before wondering why Dependabot went quiet.
          if (check) {
            const broken = results.filter(r => r.status === 'check-broken');
            const wrappers = results.reduce((n, r) => n + (r.wrappers || 0), 0);

            md.push(`Checked **${wrappers}** \`maven-wrapper.properties\` file(s) across ` +
              `**${results.length}** repo/branch combination(s).`, '');
            md.push('A file counts as broken when Dependabot can read no wrapper version from it — ' +
              'no `wrapperVersion`, no parseable `wrapperUrl`, and no version banner in `mvnw`. ' +
              'Dependabot raises while *parsing* such a file, which aborts that repository’s entire ' +
              'update job: no pull requests at all, not merely no wrapper PR.', '');

            if (!broken.length) {
              md.push('✅ Every wrapper file is readable by Dependabot.');
              write(false);
            }

            const files = broken.reduce((n, r) => n + r.broken.length, 0);
            md.push(`❌ **${files}** file(s) across **${broken.length}** repo/branch combination(s) ` +
              'would break Dependabot.', '');
            md.push('| Repo | Branch | File | Why |', '|---|---|---|---|');
            for (const r of broken) {
              for (const b of r.broken) {
                md.push(`| \`${r.repo}\` | \`${r.branch}\` | \`${b.path}\` | ${b.reason} |`);
              }
            }
            md.push('', 'Re-run this workflow with `check_only` unchecked to fix them.');
            write(true);
          }

          // ── Update mode ───────────────────────────────────────────────────────────────────
          md.push(`Target Maven **${process.env.MAVEN_VERSION}**, ` +
            `maven-wrapper **${process.env.WRAPPER_VERSION}**.`, '');
          if (of('ignored-by-dependabot').length) {
            md.push('Branches marked `ignored-by-dependabot` are held below the target because ' +
              'the repository\'s `dependabot.yml` ignores that Maven version for them.', '');
          }
          if (dry) {
            md.push('> **Dry run** — no branches or pull requests were created. ' +
              'Re-run with `dry_run` unchecked to open them.', '');
          }

          const withMerge = s => results.filter(r => r.mergeStatus === s);

          md.push(`${results.length} repo/branch combination(s) checked — ` +
            `**${of('pr-opened').length}** PR(s) opened, ` +
            `**${of('pr-updated').length}** existing PR(s) moved up, ` +
            `**${of('would-open').length + of('would-update-pr').length}** would change, ` +
            `**${of('pr-open').length}** already current, ` +
            `**${of('up-to-date').length}** up to date, ` +
            `**${of('ignored-by-dependabot').length}** held by Dependabot ignores, ` +
            `**${of('error').length}** error(s).`, '');

          // Module wrappers are the whole reason this workflow stopped being a one-file edit, so how
          // many were actually touched is worth stating rather than leaving to be inferred.
          const changedFiles = results.reduce((n, r) => n + (r.changedPaths || []).length, 0);
          const moduleFiles = results.reduce((n, r) =>
            n + (r.changedPaths || []).filter(p => p !== '.mvn/wrapper/maven-wrapper.properties').length, 0);
          if (changedFiles) {
            md.push(`**${changedFiles}** wrapper file(s) changed, ` +
              `**${moduleFiles}** of them in module directories.`, '');
          }

          const merged = withMerge('merged');
          const wouldMerge = withMerge('would-merge');
          if (merged.length || wouldMerge.length) {
            md.push(`**${merged.length}** PR(s) merged` +
              (wouldMerge.length ? `, **${wouldMerge.length}** would be merged` : '') + '.', '');
          }

          // Said plainly, so a weekly run with open green PRs and an empty Merge column
          // reads as a deliberate policy rather than as merging having quietly failed.
          if (process.env.EVENT_NAME === 'schedule') {
            md.push('> Auto-merge is off for scheduled runs — open PRs are left for a human. ' +
              'Run this workflow manually with `auto_merge` checked to merge the green ones.', '');
          }

          const interesting = results.filter(r =>
            !['up-to-date', 'no-wrapper'].includes(r.status));

          if (!interesting.length) {
            md.push('Every maintained branch is already on the target wrapper.');
          } else {
            md.push('| Repo | Branch | Files | Status | Merge | Detail |', '|---|---|---|---|---|---|');
            for (const r of interesting) {
              const detail = r.prUrl ? `[${r.detail}](${r.prUrl})` : (r.detail || '');
              const merge = r.mergeStatus
                ? `${r.mergeStatus}${r.mergeDetail ? ` — ${r.mergeDetail}` : ''}`
                : '';
              const files = (r.changedPaths || []).length
                ? `${r.changedPaths.length}/${r.wrappers || '?'}`
                : `${r.wrappers || 0}`;
              md.push(`| \`${r.repo}\` | \`${r.branch}\` | ${files} | ${r.status} | ${merge} | ${detail} |`);
            }
            md.push('', '<sub>Files: changed / total wrapper files found in directories with a pom.xml.</sub>');
          }

          const quiet = of('up-to-date').length + of('no-wrapper').length;
          if (quiet) {
            md.push('', `<sub>${of('up-to-date').length} branch(es) already current, ` +
              `${of('no-wrapper').length} with no Maven wrapper — omitted above.</sub>`);
          }

          write(false);
          JSEOF