feat(ci): label pull requests by reading effort

.github/workflows/ci.yml

@@ -61,6 +61,12 @@ jobs:
       - name: Test CI planner
         run: node --test --test-concurrency=1 scripts/ci-test-plan.test.mjs scripts/verify-windows-harness.test.mjs
 
+      # Pure Node like the planner test, and the labelling workflow imports this
+      # module directly, so a tier or exclusion change is caught here rather
+      # than by mislabelling live pull requests.
+      - name: Test PR effort classification
+        run: node --test --test-concurrency=1 scripts/pr-effort.test.mjs
+
       # Same shape and the same needs: a regenerate-and-diff contract that runs
       # on Node alone, so it belongs beside the planner test rather than behind
       # an install.

.github/workflows/pr-effort-label.yml

@@ -0,0 +1,134 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+name: PR effort label
+
+# Labels a pull request when it first asks for review, then re-checks the whole
+# open set once a day. A push changes the diff and so can change the tier, but
+# subscribing to every push would run this hundreds of times a day to correct a
+# label nobody is misled by in the meantime; the daily sweep absorbs that drift
+# and doubles as the recovery path for any event this misses.
+on:
+  pull_request_target:
+    types: [opened, reopened, ready_for_review]
+    branches: [main]
+  schedule:
+    - cron: "23 4 * * *"
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Log the tier each open pull request would get without writing labels.
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: pr-effort-label-${{ github.event.pull_request.number || github.workflow }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request_target' }}
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      # pull_request_target runs with a writable token, so the ref is pinned to
+      # the trusted default-branch commit rather than left to the event's
+      # default: pull_request_review and friends resolve to refs/pull/N/merge,
+      # and this job imports the checked-out script.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          DRY_RUN: ${{ inputs.dry_run || false }}
+        with:
+          script: |
+            const path = require("node:path")
+            const { pathToFileURL } = require("node:url")
+
+            const { planLabels } = await import(
+              pathToFileURL(path.join(process.env.GITHUB_WORKSPACE, "scripts/pr-effort.mjs")).href
+            )
+
+            const { owner, repo } = context.repo
+
+            // Reviewing a tier boundary or an exclusion means seeing it against
+            // real pull requests, which is this same sweep minus the writes.
+            const dryRun = process.env.DRY_RUN === "true"
+
+            const targets = context.payload.pull_request
+              ? [context.payload.pull_request.number]
+              : (
+                  await github.paginate(github.rest.pulls.list, {
+                    owner,
+                    repo,
+                    state: "open",
+                    per_page: 100,
+                  })
+                ).map((pull) => pull.number)
+
+            for (const pull_number of targets) {
+              const [files, current] = await Promise.all([
+                github.paginate(github.rest.pulls.listFiles, { owner, repo, pull_number, per_page: 100 }),
+                github.paginate(github.rest.issues.listLabelsOnIssue, {
+                  owner,
+                  repo,
+                  issue_number: pull_number,
+                  per_page: 100,
+                }),
+              ])
+
+              const plan = planLabels(
+                files,
+                current.map((label) => label.name),
+              )
+
+              if (dryRun) {
+                core.info(
+                  `#${pull_number}: ${plan.label} (${plan.lines} readable lines)` +
+                    ` +[${plan.addLabels.join(", ")}] -[${plan.removeLabels.join(", ")}]`,
+                )
+                continue
+              }
+
+              if (plan.addLabels.length > 0) {
+                await github.rest.issues.addLabels({
+                  owner,
+                  repo,
+                  issue_number: pull_number,
+                  labels: plan.addLabels,
+                })
+              }
+
+              for (const name of plan.removeLabels) {
+                try {
+                  await github.rest.issues.removeLabel({ owner, repo, issue_number: pull_number, name })
+                } catch (error) {
+                  // Another run may have removed it first; anything else is real.
+                  if (error.status !== 404) throw error
+                }
+              }
+
+              core.info(`#${pull_number}: ${plan.label} (${plan.lines} readable lines)`)
+            }

scripts/ci-test-plan.test.mjs

@@ -344,6 +344,7 @@ test('pull request triggers stay on an explicit allowlist', () => {
     'copilot-auto-review.yml',
     'dependency-audit.yml',
     'gitoxide-helper-admission.yml',
+    'pr-effort-label.yml',
     'release-windows-check.yml',
     'runtime-host-owner-platform.yml',
     'runtime-host-peer-admission.yml',
@@ -585,6 +586,22 @@ test('workflows never persist the job credential into the checkout', () => {
   }
 });
 
+test('a pull_request_target checkout is pinned to the trusted base commit', () => {
+  // This event hands the job a writable token while the pull request is fork
+  // controlled, so what gets checked out is what decides whether that token can
+  // reach author-supplied code. `github.sha` is the base branch commit here;
+  // `head.sha` and a bare checkout under a merge-ref event are both the pull
+  // request's own tree. Nothing else in CI would notice that edit, which is why
+  // the rule lives here rather than in a comment.
+  for (const name of readdirSync(WORKFLOW_DIR)) {
+    if (!/\bpull_request_target\b/u.test(triggerBlock(name))) continue;
+
+    for (const step of checkoutSteps(name)) {
+      assert.match(step, /\n\s+ref: \$\{\{ github\.sha \}\}\n/u, `${name}: ${step.trim()}`);
+    }
+  }
+});
+
 test('core CI runs the live Eval proxy lifecycle when Eval is selected', () => {
   const workflow = readWorkflow('ci.yml');
   const evalPackage = JSON.parse(

scripts/pr-effort.mjs

@@ -0,0 +1,90 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+// How much reading a pull request asks for. Review state is deliberately not
+// labelled here: GitHub already indexes review, check and draft state, so a
+// search qualifier answers "whose move is it" without a workflow keeping a
+// copy fresh. Pull request search has no size qualifier, which leaves reading
+// effort as the one axis a query cannot express.
+
+const EFFORT_LABELS = ['effort/XS', 'effort/S', 'effort/M', 'effort/L', 'effort/XL'];
+
+// Counted changes should track what a human actually reads. Lockfiles,
+// regenerated artifacts and binaries are verified by their own contracts, so
+// letting their line counts reach the tiers would inflate every pull request
+// that happens to touch one. A Rust dependency bump alone rewrites thousands
+// of Cargo.lock lines that nobody reviews line by line.
+const UNREAD_PATTERNS = [
+  /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|Cargo\.lock|uv\.lock)$/,
+  /(^|\/)THIRD_PARTY_(NOTICES|LICENSES)[^/]*$/,
+  /\.generated\.[cm]?[jt]sx?$/,
+  /\.snapshot\.json$/,
+  /\.min\.(js|css)$/,
+  /\.(png|jpe?g|gif|ico|webp|woff2?|ttf|sqlite|zip|gz|pdf)$/,
+];
+
+// Tier boundaries are inclusive upper bounds on readable lines. Test code is
+// not discounted anywhere here; it is reviewed too.
+const EFFORT_TIERS = [
+  { label: 'effort/XS', maxLines: 10 },
+  { label: 'effort/S', maxLines: 100 },
+  { label: 'effort/M', maxLines: 500 },
+  { label: 'effort/L', maxLines: 1000 },
+  { label: 'effort/XL', maxLines: Number.POSITIVE_INFINITY },
+];
+
+function isUnreadPath(path) {
+  const normalized = String(path).replace(/\\/g, '/');
+  return UNREAD_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+
+/**
+ * @param {Array<{filename: string, additions?: number, deletions?: number}>} files
+ */
+function countReadableLines(files = []) {
+  return files.reduce((total, file) => {
+    if (isUnreadPath(file.filename)) return total;
+    return total + (file.additions ?? 0) + (file.deletions ?? 0);
+  }, 0);
+}
+
+/**
+ * @param {Array<object>} files
+ */
+function classifyEffort(files = []) {
+  const lines = countReadableLines(files);
+  const tier = EFFORT_TIERS.find((candidate) => lines <= candidate.maxLines);
+  return { label: tier.label, lines };
+}
+
+/**
+ * @param {Array<object>} files
+ * @param {string[]} currentLabels
+ */
+export function planLabels(files = [], currentLabels = []) {
+  const { label, lines } = classifyEffort(files);
+  const current = new Set(currentLabels);
+
+  return {
+    label,
+    lines,
+    addLabels: current.has(label) ? [] : [label],
+    removeLabels: EFFORT_LABELS.filter((name) => name !== label && current.has(name)),
+  };
+}