Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

CI: Add PR build-size reports (#279)

Jamie (James) London1e9f3eae0267
diff --git a/.github/workflows/pr-build-size-comment.yml b/.github/workflows/pr-build-size-comment.yml
new file mode 100644
index 00000000..22fd1db7
--- /dev/null
+++ b/.github/workflows/pr-build-size-comment.yml
@@ -0,0 +1,341 @@
+name: PR build size comment
+
+on:
+ workflow_run:
+ workflows: [PR build size]
+ types: [completed]
+
+permissions:
+ actions: read
+ pull-requests: write
+
+concurrency:
+ group: >-
+ pr-build-size-comment-${{ github.event.workflow_run.head_repository.id || github.event.workflow_run.id }}-${{ github.event.workflow_run.head_branch || github.event.workflow_run.id }}
+ cancel-in-progress: false
+
+jobs:
+ comment:
+ if: >-
+ github.event.workflow_run.event == 'pull_request' &&
+ github.event.workflow_run.conclusion == 'success' &&
+ github.event.workflow_run.head_repository.id != null &&
+ github.event.workflow_run.head_branch != null
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ steps:
+ - name: Inspect report artifact
+ id: artifact
+ env:
+ GITHUB_TOKEN: ${{ github.token }}
+ REPOSITORY: ${{ github.repository }}
+ RUN_ID: ${{ github.event.workflow_run.id }}
+ run: |
+ node --input-type=module <<'NODE'
+ import { appendFileSync } from 'node:fs';
+
+ const expectedName = 'bento-pr-build-size';
+ const maximumArtifactBytes = 16 * 1024;
+ const runId = Number(process.env.RUN_ID);
+
+ function finish(download, reason) {
+ appendFileSync(process.env.GITHUB_OUTPUT, `download=${download}\n`);
+ console.log(reason);
+ }
+
+ if (!Number.isSafeInteger(runId) || runId <= 0) {
+ finish('false', 'No report: invalid workflow-run metadata.');
+ process.exit(0);
+ }
+
+ const artifacts = [];
+ for (let page = 1; page <= 10; page += 1) {
+ const url = new URL(
+ `https://api.github.com/repos/${process.env.REPOSITORY}/actions/runs/${runId}/artifacts`,
+ );
+ url.searchParams.set('per_page', '100');
+ url.searchParams.set('page', String(page));
+ const response = await fetch(url, {
+ headers: {
+ Accept: 'application/vnd.github+json',
+ Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
+ 'X-GitHub-Api-Version': '2022-11-28',
+ },
+ });
+ if (!response.ok) {
+ throw new Error(`Artifact listing failed with status ${response.status}.`);
+ }
+ const payload = await response.json();
+ if (!Array.isArray(payload.artifacts)) {
+ finish('false', 'No report: malformed artifact listing.');
+ process.exit(0);
+ }
+ artifacts.push(...payload.artifacts);
+ if (payload.artifacts.length < 100) break;
+ if (page === 10) {
+ finish('false', 'No report: artifact listing exceeded the scan limit.');
+ process.exit(0);
+ }
+ }
+
+ const matches = artifacts.filter(
+ (artifact) => artifact?.name === expectedName && artifact?.expired === false,
+ );
+ if (matches.length !== 1) {
+ finish('false', 'No report: expected exactly one current report artifact.');
+ process.exit(0);
+ }
+ const size = matches[0].size_in_bytes;
+ if (!Number.isSafeInteger(size) || size <= 0 || size > maximumArtifactBytes) {
+ finish('false', 'No report: artifact size is outside the allowed range.');
+ process.exit(0);
+ }
+
+ finish('true', 'Report artifact metadata is valid.');
+ NODE
+
+ - name: Download report artifact
+ id: download
+ if: steps.artifact.outputs.download == 'true'
+ continue-on-error: true
+ uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+ with:
+ name: bento-pr-build-size
+ path: ${{ runner.temp }}/bento-pr-build-size
+ repository: ${{ github.repository }}
+ run-id: ${{ github.event.workflow_run.id }}
+ github-token: ${{ github.token }}
+
+ - name: Validate report and update comment
+ if: >-
+ steps.artifact.outputs.download == 'true' &&
+ steps.download.outcome == 'success'
+ env:
+ BASE_REPOSITORY_ID: ${{ github.repository_id }}
+ GITHUB_TOKEN: ${{ github.token }}
+ HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
+ HEAD_REPOSITORY_ID: ${{ github.event.workflow_run.head_repository.id }}
+ HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+ REPORT_DIRECTORY: ${{ runner.temp }}/bento-pr-build-size
+ REPOSITORY: ${{ github.repository }}
+ run: |
+ node --input-type=module <<'NODE'
+ import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+ import { join } from 'node:path';
+
+ const marker = '<!-- bento-build-size-report -->';
+ const botId = 41898282;
+ const maximumJsonBytes = 16 * 1024;
+ const expectedApps = [
+ { id: 'bento/slides', label: '`bento/slides`' },
+ { id: 'bento/spaces', label: '`bento/spaces`' },
+ { id: 'bento/dash', label: '`bento/dash`' },
+ ];
+
+ function noOp(reason) {
+ console.log(`No comment: ${reason}`);
+ process.exit(0);
+ }
+
+ function hasExactKeys(value, keys) {
+ return value !== null &&
+ typeof value === 'object' &&
+ !Array.isArray(value) &&
+ Object.keys(value).sort().join('\0') === [...keys].sort().join('\0');
+ }
+
+ function isSha(value) {
+ return typeof value === 'string' && /^[0-9a-f]{40}$/.test(value);
+ }
+
+ function isSize(value) {
+ return Number.isSafeInteger(value) && value >= 0;
+ }
+
+ async function api(path, options = {}) {
+ const response = await fetch(`https://api.github.com${path}`, {
+ method: options.method ?? 'GET',
+ headers: {
+ Accept: 'application/vnd.github+json',
+ Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
+ 'Content-Type': 'application/json',
+ 'X-GitHub-Api-Version': '2022-11-28',
+ },
+ body: options.body === undefined ? undefined : JSON.stringify(options.body),
+ });
+ if (response.status === 404 && options.allowNotFound === true) {
+ return null;
+ }
+ if (!response.ok) {
+ throw new Error(`GitHub API request failed with status ${response.status}.`);
+ }
+ return response.status === 204 ? null : response.json();
+ }
+
+ if (!existsSync(process.env.REPORT_DIRECTORY)) {
+ noOp('artifact download produced no report directory.');
+ }
+ const entries = readdirSync(process.env.REPORT_DIRECTORY, { withFileTypes: true });
+ if (entries.length !== 1 || entries[0].name !== 'report.json' || !entries[0].isFile()) {
+ noOp('artifact contents were not exactly the expected JSON file.');
+ }
+ const reportPath = join(process.env.REPORT_DIRECTORY, 'report.json');
+ const reportStat = lstatSync(reportPath);
+ if (!reportStat.isFile() || reportStat.size <= 0 || reportStat.size > maximumJsonBytes) {
+ noOp('report JSON size is outside the allowed range.');
+ }
+
+ let report;
+ try {
+ report = JSON.parse(readFileSync(reportPath, 'utf8'));
+ } catch {
+ noOp('report JSON is malformed.');
+ }
+
+ if (!hasExactKeys(report, ['schemaVersion', 'pullRequest', 'baseSha', 'headSha', 'apps'])) {
+ noOp('report schema is invalid.');
+ }
+ if (report.schemaVersion !== 1 ||
+ !Number.isSafeInteger(report.pullRequest) ||
+ report.pullRequest <= 0 ||
+ !isSha(report.baseSha) ||
+ !isSha(report.headSha) ||
+ !Array.isArray(report.apps) ||
+ report.apps.length !== expectedApps.length) {
+ noOp('report values are invalid.');
+ }
+
+ const sizes = new Map();
+ for (const value of report.apps) {
+ if (!hasExactKeys(value, ['app', 'baseBytes', 'headBytes']) ||
+ !expectedApps.some((app) => app.id === value.app) ||
+ sizes.has(value.app) ||
+ !isSize(value.baseBytes) ||
+ !isSize(value.headBytes)) {
+ noOp('report app data is invalid.');
+ }
+ sizes.set(value.app, value);
+ }
+ if (expectedApps.some((app) => !sizes.has(app.id))) {
+ noOp('report app data is incomplete.');
+ }
+
+ const baseRepositoryId = Number(process.env.BASE_REPOSITORY_ID);
+ const headRepositoryId = Number(process.env.HEAD_REPOSITORY_ID);
+ if (!Number.isSafeInteger(baseRepositoryId) || baseRepositoryId <= 0 ||
+ !Number.isSafeInteger(headRepositoryId) || headRepositoryId <= 0 ||
+ !isSha(process.env.HEAD_SHA) ||
+ report.headSha !== process.env.HEAD_SHA ||
+ typeof process.env.HEAD_BRANCH !== 'string' ||
+ process.env.HEAD_BRANCH.length === 0) {
+ noOp('workflow-run metadata is invalid or does not match the report.');
+ }
+
+ const pullPath = `/repos/${process.env.REPOSITORY}/pulls/${report.pullRequest}`;
+ function validPull(pull) {
+ return pull?.number === report.pullRequest &&
+ pull?.state === 'open' &&
+ pull?.merged_at === null &&
+ pull?.base?.repo?.id === baseRepositoryId &&
+ pull?.base?.repo?.full_name?.toLowerCase() === process.env.REPOSITORY.toLowerCase() &&
+ typeof pull?.base?.ref === 'string' &&
+ pull.base.ref.length > 0 &&
+ pull?.base?.sha === report.baseSha &&
+ pull?.head?.repo?.id === headRepositoryId &&
+ pull?.head?.ref === process.env.HEAD_BRANCH &&
+ pull?.head?.sha === report.headSha;
+ }
+
+ let pull = await api(pullPath, { allowNotFound: true });
+ if (!validPull(pull)) {
+ noOp('the pull request is closed, merged, stale, or does not match the workflow run.');
+ }
+
+ const matchingComments = [];
+ for (let page = 1; page <= 100; page += 1) {
+ const comments = await api(
+ `/repos/${process.env.REPOSITORY}/issues/${report.pullRequest}/comments?per_page=100&page=${page}`,
+ );
+ if (!Array.isArray(comments)) {
+ noOp('pull-request comments response was malformed.');
+ }
+ matchingComments.push(...comments.filter(
+ (comment) => comment?.user?.login === 'github-actions[bot]' &&
+ comment?.user?.id === botId &&
+ typeof comment?.body === 'string' &&
+ (comment.body === marker || comment.body.startsWith(`${marker}\n`)),
+ ));
+ if (comments.length < 100) break;
+ if (page === 100) {
+ noOp('pull request has too many comments to scan safely.');
+ }
+ }
+ if (matchingComments.length > 1) {
+ noOp('multiple matching bot comments already exist.');
+ }
+
+ function kib(bytes) {
+ return `${(bytes / 1024).toFixed(1)} KiB`;
+ }
+
+ function change(baseBytes, headBytes) {
+ const delta = headBytes - baseBytes;
+ const absolute = delta > 0 ? `+${kib(delta)}` : kib(delta);
+ if (baseBytes === 0) {
+ return `${absolute} (${headBytes === 0 ? '0.00%' : 'n/a'})`;
+ }
+ const percent = (delta / baseBytes) * 100;
+ const formattedPercent = `${percent > 0 ? '+' : ''}${percent.toFixed(2)}%`;
+ return `${absolute} (${formattedPercent})`;
+ }
+
+ function escapeHtml(value) {
+ return value
+ .replaceAll('&', '&amp;')
+ .replaceAll('<', '&lt;')
+ .replaceAll('>', '&gt;')
+ .replaceAll('"', '&quot;')
+ .replaceAll("'", '&#39;');
+ }
+
+ const rows = expectedApps.map(({ id, label }) => {
+ const value = sizes.get(id);
+ return `| ${label} | ${kib(value.baseBytes)} | ${kib(value.headBytes)} | ${change(value.baseBytes, value.headBytes)} |`;
+ });
+ pull = await api(pullPath, { allowNotFound: true });
+ if (!validPull(pull)) {
+ noOp('the pull request changed before the comment could be written.');
+ }
+
+ const updatedAt = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+ const body = [
+ marker,
+ '### Build size',
+ '',
+ `<code>${escapeHtml(pull.base.ref)}</code> (<code>${report.baseSha.slice(0, 7)}</code>) → <code>${escapeHtml(pull.head.ref)}</code> (<code>${report.headSha.slice(0, 7)}</code>)`,
+ '',
+ '| app | base | PR | change |',
+ '| --- | ---: | ---: | ---: |',
+ ...rows,
+ '',
+ `Updated: \`${updatedAt}\``,
+ ].join('\n');
+
+ if (matchingComments.length === 1) {
+ const commentId = matchingComments[0].id;
+ if (!Number.isSafeInteger(commentId) || commentId <= 0) {
+ noOp('the existing comment id is invalid.');
+ }
+ await api(`/repos/${process.env.REPOSITORY}/issues/comments/${commentId}`, {
+ method: 'PATCH',
+ body: { body },
+ });
+ console.log('Updated the advisory build-size comment.');
+ } else {
+ await api(`/repos/${process.env.REPOSITORY}/issues/${report.pullRequest}/comments`, {
+ method: 'POST',
+ body: { body },
+ });
+ console.log('Created the advisory build-size comment.');
+ }
+ NODE
diff --git a/.github/workflows/pr-build-size.yml b/.github/workflows/pr-build-size.yml
new file mode 100644
index 00000000..b88bd419
--- /dev/null
+++ b/.github/workflows/pr-build-size.yml
@@ -0,0 +1,149 @@
+name: PR build size
+
+on:
+ pull_request:
+ types: [opened, reopened, synchronize, edited]
+
+permissions:
+ contents: read
+
+jobs:
+ measure:
+ if: github.event.action != 'edited' || github.event.changes.base != null
+ concurrency:
+ # Keep unrelated title/body edits from cancelling a real measurement.
+ group: pr-build-size-${{ github.event.pull_request.number }}
+ cancel-in-progress: true
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+ env:
+ CI: "true"
+ steps:
+ - name: Check out base commit
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ repository: ${{ github.event.pull_request.base.repo.full_name }}
+ ref: ${{ github.event.pull_request.base.sha }}
+ path: base
+ persist-credentials: false
+
+ - name: Set up Node.js
+ uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+ with:
+ node-version: 24
+
+ - name: Build base bento/slides
+ working-directory: base/slides
+ run: |
+ npm ci
+ npm run build:single
+
+ - name: Build base bento/spaces
+ working-directory: base/spaces
+ run: |
+ npm ci
+ npm run build:single
+
+ - name: Build base bento/dash
+ working-directory: base/dash
+ run: |
+ npm ci
+ npm run build:single
+
+ - name: Record base sizes
+ env:
+ BASE_ROOT: ${{ github.workspace }}/base
+ OUTPUT_PATH: ${{ runner.temp }}/bento-base-sizes.json
+ run: |
+ node --input-type=module <<'NODE'
+ import { statSync, writeFileSync } from 'node:fs';
+ import { join } from 'node:path';
+
+ const files = {
+ 'bento/slides': 'slides/dist-single/Bento_Slides.bento.html',
+ 'bento/spaces': 'spaces/dist-single/Bento_Spaces.bento.html',
+ 'bento/dash': 'dash/dist-single/Bento_Dash.bento.html',
+ };
+ const sizes = Object.fromEntries(
+ Object.entries(files).map(([app, file]) => [
+ app,
+ statSync(join(process.env.BASE_ROOT, file)).size,
+ ]),
+ );
+ writeFileSync(process.env.OUTPUT_PATH, JSON.stringify(sizes), { mode: 0o600 });
+ NODE
+
+ - name: Remove base checkout
+ run: rm -rf -- "$GITHUB_WORKSPACE/base"
+
+ - name: Check out PR head commit
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ repository: ${{ github.event.pull_request.head.repo.full_name }}
+ ref: ${{ github.event.pull_request.head.sha }}
+ path: head
+ persist-credentials: false
+
+ - name: Build PR bento/slides
+ working-directory: head/slides
+ run: |
+ npm ci
+ npm run build:single
+
+ - name: Build PR bento/spaces
+ working-directory: head/spaces
+ run: |
+ npm ci
+ npm run build:single
+
+ - name: Build PR bento/dash
+ working-directory: head/dash
+ run: |
+ npm ci
+ npm run build:single
+
+ - name: Create report
+ env:
+ BASE_SHA: ${{ github.event.pull_request.base.sha }}
+ BASE_SIZES_PATH: ${{ runner.temp }}/bento-base-sizes.json
+ HEAD_ROOT: ${{ github.workspace }}/head
+ HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+ PR_NUMBER: ${{ github.event.pull_request.number }}
+ REPORT_DIRECTORY: ${{ runner.temp }}/bento-pr-build-size
+ run: |
+ node --input-type=module <<'NODE'
+ import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+ import { join } from 'node:path';
+
+ const files = {
+ 'bento/slides': 'slides/dist-single/Bento_Slides.bento.html',
+ 'bento/spaces': 'spaces/dist-single/Bento_Spaces.bento.html',
+ 'bento/dash': 'dash/dist-single/Bento_Dash.bento.html',
+ };
+ const baseSizes = JSON.parse(readFileSync(process.env.BASE_SIZES_PATH, 'utf8'));
+ const report = {
+ schemaVersion: 1,
+ pullRequest: Number(process.env.PR_NUMBER),
+ baseSha: process.env.BASE_SHA,
+ headSha: process.env.HEAD_SHA,
+ apps: Object.entries(files).map(([app, file]) => ({
+ app,
+ baseBytes: baseSizes[app],
+ headBytes: statSync(join(process.env.HEAD_ROOT, file)).size,
+ })),
+ };
+ mkdirSync(process.env.REPORT_DIRECTORY, { recursive: true });
+ writeFileSync(
+ join(process.env.REPORT_DIRECTORY, 'report.json'),
+ JSON.stringify(report),
+ { mode: 0o600 },
+ );
+ NODE
+
+ - name: Upload report
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+ with:
+ name: bento-pr-build-size
+ path: ${{ runner.temp }}/bento-pr-build-size/report.json
+ if-no-files-found: error
+ retention-days: 1
diff --git a/docs/pr-build-size-design.md b/docs/pr-build-size-design.md
new file mode 100644
index 00000000..0be3699a
--- /dev/null
+++ b/docs/pr-build-size-design.md
@@ -0,0 +1,217 @@
+# Advisory PR build-size report
+
+Status: implemented by `.github/workflows/pr-build-size.yml` and
+`.github/workflows/pr-build-size-comment.yml`. This document does not authorize
+release, publishing, or deployment work.
+
+Related discussion: <https://github.com/nyblnet/bento/discussions/178>
+
+## Goal
+
+Add one best-effort pull-request comment showing how the built single-file
+shells changed relative to the PR's base commit.
+
+This is a quality-of-life aid for good-faith contributors. It is not a merge
+gate, an attestation, or a guarantee that a PR author could not fabricate the
+reported values.
+
+## Non-goals
+
+- Do not fail a PR because its build grows.
+- Do not replace the existing shell-size ceilings.
+- Do not defend against a PR deliberately fabricating its measurements.
+- Do not report build failures, cancellations, missing artifacts, or every
+ workflow edge case in the PR comment.
+- Do not guarantee that the comment always describes the newest workflow run.
+ The displayed base and head SHAs make its measurement point explicit.
+- Do not add a bot account, personal access token, external service, database,
+ historical dashboard, release step, signing step, or deployment step.
+- Do not block, delay, reopen, close, merge, label, or otherwise change a PR.
+
+## Security boundary
+
+Code from a PR is untrusted even though the reported number is advisory.
+
+1. A job that checks out, installs, or executes PR code receives no secrets and
+ no write-capable token.
+2. A job with permission to comment never checks out or executes PR code,
+ restores a PR-controlled cache, or invokes a script supplied by the PR.
+3. Data crossing between the jobs is parsed as untrusted data. It never becomes
+ shell code, JavaScript source, a file path, arbitrary Markdown, or an
+ unverified mutation target.
+4. The privileged workflow can only create or update its fixed-format advisory
+ comment. It does not push code or change PR state.
+
+Do not use `pull_request_target` to build the PR. Use GitHub's recommended
+privilege separation: an unprivileged `pull_request` workflow measures, then a
+trusted `workflow_run` workflow comments.
+
+## Proposed design
+
+### 1. Unprivileged measurement workflow
+
+Trigger on the exact `pull_request` activity types `opened`, `reopened`,
+`synchronize`, and `edited`. For `edited`, run only when
+`github.event.changes.base` is present, so base retargeting is measured without
+rebuilding for unrelated title or body edits. Declare only `contents: read` and
+reference no repository secrets.
+
+On one GitHub-hosted runner with a pinned Node version and a 20-minute job
+timeout:
+
+1. Check out the exact base SHA with `persist-credentials: false`.
+2. Install and build the current single-file apps.
+3. Record the generated HTML byte counts outside the checkout directory.
+4. Clean the checkout.
+5. Check out the exact head SHA with `persist-credentials: false`.
+6. Repeat the installs, builds, and measurements.
+7. If every build succeeds, use a full-SHA-pinned
+ `actions/upload-artifact` action to upload one small, fixed-name JSON
+ artifact with short retention.
+
+Build the base first and measure both commits on the same runner to reduce
+environmental noise. Measure the final `.bento.html` files directly; do not add
+a second gzip metric.
+
+The initial report covers:
+
+- `bento/slides`
+- `bento/spaces`
+- `bento/dash`
+
+The versioned artifact contains only:
+
+- the integer PR number as an untrusted, read-only lookup hint;
+- the measured base and head commit SHAs;
+- fixed, allowlisted app identifiers;
+- non-negative integer `baseBytes` and `headBytes` values.
+
+If a build fails, the measurement workflow fails and produces no report
+artifact. That is an accepted best-effort outcome.
+
+### 2. Privileged comment workflow
+
+Trigger with `workflow_run` when the named measurement workflow completes, but
+continue only when its original event was `pull_request` and its conclusion was
+`success`.
+
+Grant only:
+
+- `actions: read`, to download that exact run's artifact;
+- `pull-requests: write`, to create or update the advisory comment.
+
+Set a 5-minute timeout on the commenter job.
+
+The workflow file lives on the default branch. The workflow must not check out
+the repository, install dependencies, restore caches, build anything, or
+execute artifact contents.
+
+Serialize commenter runs using the head-repository ID and head branch from
+GitHub's `workflow_run` metadata, never the artifact's untrusted PR-number
+value. Set `cancel-in-progress: false`; this only sequences advisory comment
+writes and does not delay or alter PR operations. It may conservatively
+serialize multiple comments originating from the same fork branch, which is
+acceptable for this best-effort feature. If the required head metadata is
+missing, exit successfully without changing anything. Do not depend on
+`workflow_run.pull_requests` being populated.
+
+It should:
+
+1. Take the repository, workflow-run ID, head-repository ID, head branch, and
+ head SHA from GitHub's event metadata.
+2. Find exactly one non-expired artifact with the expected name from that exact
+ run. Require a small size limit, such as 16 KiB.
+3. Use a full-SHA-pinned `actions/download-artifact` action to download it into
+ the runner's temporary directory and read only the expected JSON file, also
+ capped at 16 KiB.
+4. Validate the schema version, integer PR number, commit SHAs, complete app
+ allowlist, and non-negative integer sizes.
+5. Use the artifact PR number only for a read-only API lookup. Before any write,
+ continue only when the fetched PR targets this repository, its head-
+ repository ID and head branch match the workflow-run metadata, its current
+ head SHA matches both the artifact and workflow run, and its current base SHA
+ matches the artifact.
+6. If the PR is closed or merged, exit successfully without changing anything.
+ This observes PR state but never constrains normal PR operations.
+7. Generate the comment from a fixed Markdown template. Only validated numbers,
+ formatted allowlisted app names, safely HTML-escaped branch names from the
+ revalidated PR, and a workflow-generated UTC timestamp enter the template.
+8. Paginate PR comments and locate the exact
+ `<!-- bento-build-size-report -->` marker on a comment authored by
+ `github-actions[bot]`. Update that comment, or create it if none exists.
+
+Any missing, duplicate, malformed, oversized, stale, or otherwise unexpected
+input causes a successful no-op. Same-PR commenter runs are serialized; a later
+valid run may overwrite the earlier report because this report is advisory.
+
+### 3. Comment format
+
+Use a small table:
+
+| app | base | PR | change |
+| --- | ---: | ---: | ---: |
+| `bento/slides` | 560.0 KiB | 561.2 KiB | +1.2 KiB (+0.21%) |
+
+Use one deterministic rounding rule, handle a zero-byte base without division
+by zero, and show the safely escaped base and head branch names with their short
+SHAs. End with the workflow-generated update time in ISO 8601 UTC format.
+
+## Implementation constraints
+
+- Use only GitHub-maintained actions. The only additions to the actions already
+ used by the repository are `actions/upload-artifact` and
+ `actions/download-artifact`, solely for the bounded JSON transfer.
+- Pin every `uses:` reference to a verified full-length commit SHA and record
+ its release tag in a same-line comment.
+- Pass untrusted values through action inputs or environment variables. Never
+ splice them into generated shell or JavaScript source.
+- Keep the measurement and commenting workflows separate from the existing
+ `CI` workflow so their permissions remain obvious.
+- Add PR-scoped concurrency to cancel superseded measurement runs.
+- Add separate commenter concurrency keyed by the workflow run's head-
+ repository ID and head branch, with `cancel-in-progress: false`. This applies
+ only to advisory comment publication, never to PR operations or existing CI.
+- Keep the report informational and optional; it must not become a required
+ status check.
+- Bound the measurement and commenter jobs with 20-minute and 5-minute
+ `timeout-minutes` values, respectively.
+- Never add signing, release, publishing, or deployment permissions.
+
+## Verification plan
+
+1. Compare reported byte counts with local file sizes.
+2. Test successful same-repository and fork PRs, including a fork run whose
+ `workflow_run.pull_requests` array is empty.
+3. Confirm `synchronize` and base-changing `edited` events run measurement,
+ while unrelated `edited` events do not.
+4. Confirm a later successful push normally updates the existing bot comment.
+5. Confirm failed builds and missing, malformed, duplicate, oversized, or stale
+ artifacts safely produce no comment update.
+6. Confirm incorrect PR numbers, repositories, app identifiers, and base or head
+ SHAs safely produce no comment update.
+7. Confirm a closed or merged PR causes a successful no-op and no PR state
+ change.
+8. Confirm both checkouts use `persist-credentials: false`.
+9. Inspect the effective permissions of both workflows.
+10. Confirm the privileged workflow never checks out or executes PR-controlled
+ content and receives no secrets.
+11. Confirm every action is pinned to its intended upstream full commit SHA.
+12. Trigger overlapping commenter runs for one PR and confirm they update one
+ marker comment without affecting the PR or its existing checks.
+13. Confirm the measurement and commenter jobs declare 20-minute and 5-minute
+ timeouts, respectively.
+14. Confirm existing CI, size ceilings, shell gates, and release behavior remain
+ unchanged.
+
+## Acceptance criteria
+
+- A successful good-faith PR measurement produces one advisory comparison
+ comment containing its measured base and head SHAs.
+- Fork PR code runs without secrets or write permission.
+- The commenting workflow runs no PR code and has only artifact-read and
+ PR-comment permissions.
+- Untrusted artifact values cannot cause a write to an unverified PR or become
+ executable code or arbitrary Markdown.
+- Exceptional, invalid, stale, failed, cancelled, or closed cases safely do
+ nothing and never interfere with PR operations.
+- The feature never blocks merging or changes release artifacts.