Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

ci: report published package size and new runtime dependencies on each PR, in the build job (#9161)

Cindy Zhang9cbdd7b002f4
diff --git a/.github/scripts/ci-tooling-routing.test.mjs b/.github/scripts/ci-tooling-routing.test.mjs
index 69ef628cc2..9267e4f894 100644
--- a/.github/scripts/ci-tooling-routing.test.mjs
+++ b/.github/scripts/ci-tooling-routing.test.mjs
@@ -263,15 +263,17 @@ describe('Node-tooling CI routing', () => {
const install = step(job, "Install the merge base's dependencies");
expect(install.run).toBe('pnpm install --frozen-lockfile');
expect(install.if).not.toContain('steps.download');
- // Only Main's own run on main for the merge-base commit counts.
+ // Only Main's own run on main for the merge-base commit counts; both
+ // merge-base lookups share one helper (main-artifact.test.mjs).
const find = step(job, "Find main's build of the merge base").with.script;
- expect(find).toContain("candidate.workflow_run?.head_branch === 'main'");
- expect(find).toContain(
- 'candidate.workflow_run?.head_sha === process.env.BASE_SHA',
- );
- expect(find).toContain(
- 'candidate.workflow_run?.head_repository_id === candidate.workflow_run?.repository_id',
- );
+ expect(find).toContain('.github/scripts/lib/main-artifact.cjs');
+ expect(find).toContain('sha: process.env.BASE_SHA');
+ const packageFind = step(
+ ci.jobs['build-storybook'],
+ "Find main's package size for the merge base",
+ ).with.script;
+ expect(packageFind).toContain('.github/scripts/lib/main-artifact.cjs');
+ expect(packageFind).toContain('sha: process.env.BASE_SHA');
});
it('builds no Sandbox and builds Storybook once per pull-request run', () => {
diff --git a/.github/scripts/generate-pr-comment.js b/.github/scripts/generate-pr-comment.js
index addace1fea..428cca610b 100644
--- a/.github/scripts/generate-pr-comment.js
+++ b/.github/scripts/generate-pr-comment.js
@@ -3,16 +3,17 @@
/**
* @description Generates and posts PR comment with analysis results
- * @input --analysis <file> --base-stats <file> --a11y <file> --visual <file> --storybook-url <url> --sandbox-url <url> --preview-state <state> --source-conclusion <conclusion> --run-url <url>
+ * @input --analysis <file> --base-stats <file> --package-size <file> --a11y <file> --visual <file> --storybook-url <url> --sandbox-url <url> --preview-state <state> --source-conclusion <conclusion> --run-url <url>
* @output Formatted markdown comment body to stdout
*/
const fs = require('node:fs');
const {buildA11ySection} = require('./lib/a11y-format');
const {buildVisualSection} = require('./lib/visual-format');
+const {renderPackageSizeSection} = require('./lib/package-size');
// Report-file strings render as literal inline text, report numbers as
// numbers — the comment's structure comes only from this file's literals.
-const {inline, num} = require('./lib/report-text');
+const {inline, num, sizeText} = require('./lib/report-text');
const args = process.argv.slice(2);
const getArg = name => {
@@ -22,6 +23,7 @@ const getArg = name => {
const analysisFile = getArg('analysis') || 'analysis.json';
const baseStatsFile = getArg('base-stats');
+const packageSizeFile = getArg('package-size');
const a11yFile = getArg('a11y') || 'a11y-report.json';
const visualFile = getArg('visual');
const runUrl = getArg('run-url') || '';
@@ -98,13 +100,6 @@ function bytesDelta(after, before) {
: null;
}
-// A measured byte count as text, or N/A. Only numbers reach the output.
-function sizeText(bytes) {
- if (typeof bytes !== 'number' || !Number.isFinite(bytes)) return 'N/A';
- if (Math.abs(bytes) < 1024) return `${bytes}B`;
- return `${(bytes / 1024).toFixed(1)}KB`;
-}
-
function signedSizeText(delta) {
if (delta === null) return 'N/A';
return delta > 0 ? `+${sizeText(delta)}` : sizeText(delta);
@@ -301,6 +296,22 @@ if (analysis.bundleDelta) {
bundleSection += `**Bundle size ${direction}:** ${delta > 0 ? '+' : ''}${delta} bytes\n\n`;
}
+// Published package sizes from build-storybook's package-size check: the
+// download and unpacked size of every published package, base against head,
+// and any runtime dependency added or removed. The caller has already matched
+// its head.
+let packageSizeSection = '';
+if (packageSizeFile) {
+ try {
+ packageSizeSection = renderPackageSizeSection(
+ JSON.parse(fs.readFileSync(packageSizeFile, 'utf8')),
+ inline,
+ );
+ } catch (e) {
+ console.error('Warning: Could not read package size report:', e.message);
+ }
+}
+
// Build storybook link section
let storybookSection = '';
if (storybookUrl) {
@@ -356,7 +367,7 @@ const body = `## PR Analysis Report
<!-- astryx-pr-analysis -->
${diffModeCaveat}${previewAvailabilitySection}${storybookSection}${sandboxSection}${componentSection || (sizeSection ? '' : '_No new or modified components detected._\n\n')}
-${sizeSection}${budgetSection}${bundleSection}
+${sizeSection}${budgetSection}${bundleSection}${packageSizeSection}
${a11ySection}
${visualSection}---
diff --git a/.github/scripts/generate-pr-comment.test.mjs b/.github/scripts/generate-pr-comment.test.mjs
index c1b02c57ce..c96e933971 100644
--- a/.github/scripts/generate-pr-comment.test.mjs
+++ b/.github/scripts/generate-pr-comment.test.mjs
@@ -306,3 +306,81 @@ describe('generate-pr-comment touch-only budget', () => {
expect(out).not.toContain('Touch-only size budget');
});
});
+
+describe('published package size', () => {
+ function withPackageSize(report) {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-package-size-'));
+ try {
+ const file = path.join(dir, 'package-size.json');
+ fs.writeFileSync(file, JSON.stringify(report));
+ return runComment({newComponents: [], modifiedComponents: []}, [
+ '--package-size',
+ file,
+ ]);
+ } finally {
+ fs.rmSync(dir, {recursive: true, force: true});
+ }
+ }
+
+ const sizes = (packedBytes, files = 10) => ({
+ packedBytes,
+ unpackedBytes: packedBytes * 4,
+ files,
+ });
+
+ it('renders the section after the bundle summary, with new dependencies', () => {
+ const out = withPackageSize({
+ headSha: 'a'.repeat(40),
+ budget: {packedPercent: 5, packedMinBytes: 1024},
+ packages: [
+ {
+ name: '@astryxdesign/core',
+ base: sizes(100000, 10),
+ head: sizes(110000, 12),
+ overBudget: true,
+ },
+ ],
+ addedDependencies: [
+ {
+ package: '@astryxdesign/core',
+ field: 'dependencies',
+ name: 'left-pad',
+ range: '^1.3.0',
+ },
+ ],
+ removedDependencies: [],
+ verdict: 'over-budget',
+ });
+ expect(out.indexOf('### Bundle Size Summary')).toBeLessThan(
+ out.indexOf('### Published Package Size'),
+ );
+ expect(out).toContain(
+ '| @astryxdesign/core | 97.7KB | 107.4KB | +9.8KB (+10.0%) ⚠️ |',
+ );
+ expect(out).toContain('| 10 → 12 |');
+ expect(out).toContain('left-pad');
+ expect(out).toContain('**⚠️ Over the package budget:**');
+ });
+
+ it('renders report strings as literal text', () => {
+ const out = withPackageSize({
+ packages: [
+ {
+ name: '<img src=x onerror=alert(1)>',
+ base: sizes(1000),
+ head: sizes(2000),
+ overBudget: false,
+ },
+ ],
+ addedDependencies: [],
+ removedDependencies: [],
+ verdict: 'pass',
+ });
+ expect(out).not.toContain('<img src=x');
+ });
+
+ it('leaves the section out without a report', () => {
+ const out = runComment({newComponents: [], modifiedComponents: []});
+ expect(out).not.toContain('Published Package Size');
+ });
+});
diff --git a/.github/scripts/lib/main-artifact.cjs b/.github/scripts/lib/main-artifact.cjs
new file mode 100644
index 0000000000..4bbd3b294a
--- /dev/null
+++ b/.github/scripts/lib/main-artifact.cjs
@@ -0,0 +1,35 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file main-artifact.cjs
+ * @input An Octokit client, the repository, an artifact name, and the commit
+ * it must belong to
+ * @output The id of the workflow run on `main` that uploaded that artifact for
+ * that exact commit, or null
+ * @position Shared by the CI jobs that read what Main keeps for a merge base
+ * (its package builds, its package-size measurement), so each trusts the
+ * same thing: only Main's own run on `main` for this exact commit, in this
+ * repository. A pull request's run can upload an artifact under any name.
+ */
+
+'use strict';
+
+async function mainArtifactRunId({github, owner, repo, name, sha}) {
+ const {data} = await github.rest.actions.listArtifactsForRepo({
+ owner,
+ repo,
+ name,
+ per_page: 100,
+ });
+ const artifact = data.artifacts.find(
+ candidate =>
+ !candidate.expired &&
+ candidate.workflow_run?.head_branch === 'main' &&
+ candidate.workflow_run?.head_sha === sha &&
+ candidate.workflow_run?.head_repository_id ===
+ candidate.workflow_run?.repository_id,
+ );
+ return artifact ? String(artifact.workflow_run.id) : null;
+}
+
+module.exports = {mainArtifactRunId};
diff --git a/.github/scripts/lib/main-artifact.test.mjs b/.github/scripts/lib/main-artifact.test.mjs
new file mode 100644
index 0000000000..160d1accb7
--- /dev/null
+++ b/.github/scripts/lib/main-artifact.test.mjs
@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file main-artifact.test.mjs
+ * Pins which kept artifact a merge-base lookup trusts: only one Main's own run
+ * on `main` uploaded for that exact commit in this repository, unexpired.
+ */
+
+import {describe, expect, it, vi} from 'vitest';
+import lookup from './main-artifact.cjs';
+
+const {mainArtifactRunId} = lookup;
+const SHA = 'a'.repeat(40);
+
+function github(artifacts) {
+ return {
+ rest: {
+ actions: {
+ listArtifactsForRepo: vi.fn(async () => ({data: {artifacts}})),
+ },
+ },
+ };
+}
+
+const artifact = (overrides = {}, run = {}) => ({
+ expired: false,
+ ...overrides,
+ workflow_run: {
+ id: 42,
+ head_branch: 'main',
+ head_sha: SHA,
+ head_repository_id: 1,
+ repository_id: 1,
+ ...run,
+ },
+});
+
+describe('mainArtifactRunId', () => {
+ it("returns Main's run for the exact commit", async () => {
+ const client = github([artifact()]);
+ await expect(
+ mainArtifactRunId({
+ github: client,
+ owner: 'meta',
+ repo: 'astryx',
+ name: 'x',
+ sha: SHA,
+ }),
+ ).resolves.toBe('42');
+ expect(client.rest.actions.listArtifactsForRepo).toHaveBeenCalledWith(
+ expect.objectContaining({name: 'x', owner: 'meta', repo: 'astryx'}),
+ );
+ });
+
+ it.each([
+ ['an expired artifact', artifact({expired: true})],
+ ['a pull request branch', artifact({}, {head_branch: 'feature'})],
+ ['another commit', artifact({}, {head_sha: 'b'.repeat(40)})],
+ ['a fork', artifact({}, {head_repository_id: 2})],
+ ])('ignores %s', async (_label, candidate) => {
+ await expect(
+ mainArtifactRunId({
+ github: github([candidate]),
+ owner: 'meta',
+ repo: 'astryx',
+ name: 'x',
+ sha: SHA,
+ }),
+ ).resolves.toBeNull();
+ });
+});
diff --git a/.github/scripts/lib/package-size.js b/.github/scripts/lib/package-size.js
new file mode 100644
index 0000000000..72af2c5c67
--- /dev/null
+++ b/.github/scripts/lib/package-size.js
@@ -0,0 +1,306 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file package-size.js
+ * @input A built workspace (every published package's files on disk) and, to
+ * compare, two measurements
+ * @output Each published package's tarball size (gzip, as npm downloads it),
+ * unpacked size, file count and runtime dependencies; a base-against-head
+ * comparison with an advisory budget flag; and that comparison as Markdown
+ * @position Shared by package-size.mjs (CI's build-storybook job on a pull
+ * request, and Main's typecheck job, which keeps each main commit's
+ * measurement for pull requests to compare against) and by
+ * generate-pr-comment.js, which renders the comparison in the PR report.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const {execFile} = require('node:child_process');
+const {num, sizeText} = require('./report-text');
+
+/**
+ * A package is flagged when its tarball grows by more than this share of its
+ * base size and by at least MIN_BYTES; the floor keeps a small package from
+ * being flagged for a few hundred bytes. The flag is advisory: it asks the
+ * author, as the component touch-only budget does, and fails nothing.
+ */
+const PACKED_BUDGET_PERCENT = 5;
+const PACKED_BUDGET_MIN_BYTES = 1024;
+
+/** Dependency fields a consumer installs or must provide. */
+const RUNTIME_DEPENDENCY_FIELDS = ['dependencies', 'peerDependencies'];
+
+/** The workspace directories that can hold a published package. */
+const PACKAGE_GROUPS = ['packages', 'packages/themes'];
+
+/** Packages npm receives: public, in the scope, not canary-only. */
+function publishedPackages(root) {
+ const found = [];
+ for (const group of PACKAGE_GROUPS) {
+ const groupDir = path.join(root, group);
+ if (!fs.existsSync(groupDir)) continue;
+ for (const entry of fs.readdirSync(groupDir, {withFileTypes: true})) {
+ if (!entry.isDirectory()) continue;
+ const directory = path.join(groupDir, entry.name);
+ const manifestPath = path.join(directory, 'package.json');
+ if (!fs.existsSync(manifestPath)) continue;
+ const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+ if (
+ manifest.name?.startsWith('@astryxdesign/') &&
+ manifest.private !== true &&
+ manifest.astryx?.canaryOnly !== true
+ )
+ found.push({directory, manifest});
+ }
+ }
+ return found.sort((a, b) => a.manifest.name.localeCompare(b.manifest.name));
+}
+
+function runtimeDependencies(manifest) {
+ const dependencies = {};
+ for (const field of RUNTIME_DEPENDENCY_FIELDS) {
+ for (const [name, range] of Object.entries(manifest[field] || {}))
+ dependencies[`${field}:${name}`] = String(range);
+ }
+ return dependencies;
+}
+
+/**
+ * `npm pack --dry-run` lists what the package's `files` field ships and the
+ * tarball's size without writing it. Lifecycle scripts are skipped: the
+ * packages are already built, and some packages' prepack builds them again.
+ */
+function npmPackDryRun(directory) {
+ return new Promise((resolve, reject) => {
+ execFile(
+ 'npm',
+ ['pack', '--dry-run', '--json', '--ignore-scripts', '--silent'],
+ {cwd: directory, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024},
+ (error, stdout) => {
+ if (error) return reject(error);
+ try {
+ resolve(JSON.parse(stdout)[0]);
+ } catch (parseError) {
+ reject(parseError);
+ }
+ },
+ );
+ });
+}
+
+/**
+ * Every published package, packed side by side: the largest package's pack
+ * is most of the time, so the others add little.
+ */
+async function measurePackages(root, pack = npmPackDryRun) {
+ const published = publishedPackages(root);
+ const results = await Promise.all(
+ published.map(({directory}) => pack(directory)),
+ );
+ const packages = {};
+ published.forEach(({manifest}, index) => {
+ const result = results[index];
+ packages[manifest.name] = {
+ packedBytes: result.size,
+ unpackedBytes: result.unpackedSize,
+ files: result.entryCount,
+ dependencies: runtimeDependencies(manifest),
+ };
+ });
+ return {schema: 1, packages};
+}
+
+function isMeasured(bytes) {
+ return typeof bytes === 'number' && Number.isFinite(bytes);
+}
+
+function overBudget(baseBytes, headBytes) {
+ if (!isMeasured(baseBytes) || !isMeasured(headBytes) || baseBytes <= 0)
+ return false;
+ const delta = headBytes - baseBytes;
+ return (
+ delta >= PACKED_BUDGET_MIN_BYTES &&
+ (delta / baseBytes) * 100 > PACKED_BUDGET_PERCENT
+ );
+}
+
+function splitDependencyKey(key) {
+ const separator = key.indexOf(':');
+ return {field: key.slice(0, separator), name: key.slice(separator + 1)};
+}
+
+/**
+ * Head against base, package by package. Without a base measurement every
+ * row keeps its head figures, nothing is over budget, and the verdict says
+ * the base was not measured.
+ */
+function comparePackageSizes({
+ head,
+ base,
+ headSha = '',
+ baseSha = '',
+ baseReason = '',
+}) {
+ const headPackages = head?.packages || {};
+ const basePackages = base?.packages || null;
+ const names = [
+ ...new Set([
+ ...Object.keys(headPackages),
+ ...Object.keys(basePackages || {}),
+ ]),
+ ].sort();
+ const packages = [];
+ const addedDependencies = [];
+ const removedDependencies = [];
+ for (const name of names) {
+ const now = headPackages[name] || null;
+ const before = basePackages ? basePackages[name] || null : null;
+ packages.push({
+ name,
+ base: before && {
+ packedBytes: before.packedBytes,
+ unpackedBytes: before.unpackedBytes,
+ files: before.files,
+ },
+ head: now && {
+ packedBytes: now.packedBytes,
+ unpackedBytes: now.unpackedBytes,
+ files: now.files,
+ },
+ overBudget: overBudget(before?.packedBytes, now?.packedBytes),
+ });
+ if (!basePackages || !now) continue;
+ const beforeDependencies = before?.dependencies || {};
+ const nowDependencies = now.dependencies || {};
+ for (const [key, range] of Object.entries(nowDependencies)) {
+ if (key in beforeDependencies) continue;
+ addedDependencies.push({
+ package: name,
+ ...splitDependencyKey(key),
+ range,
+ });
+ }
+ if (!before) continue;
+ for (const [key, range] of Object.entries(beforeDependencies)) {
+ if (key in nowDependencies) continue;
+ removedDependencies.push({
+ package: name,
+ ...splitDependencyKey(key),
+ range,
+ });
+ }
+ }
+ const over = packages.some(entry => entry.overBudget);
+ const verdict = !basePackages ? 'no-base' : over ? 'over-budget' : 'pass';
+ return {
+ schema: 1,
+ headSha,
+ baseSha,
+ ...(basePackages ? {} : {baseReason: baseReason || 'not-kept'}),
+ budget: {
+ packedPercent: PACKED_BUDGET_PERCENT,
+ packedMinBytes: PACKED_BUDGET_MIN_BYTES,
+ },
+ packages,
+ addedDependencies,
+ removedDependencies,
+ verdict,
+ };
+}
+
+function deltaText(after, before) {
+ if (!isMeasured(after) || !isMeasured(before)) return 'N/A';
+ const delta = after - before;
+ const percent =
+ before > 0 && delta !== 0
+ ? ` (${delta > 0 ? '+' : ''}${((delta / before) * 100).toFixed(1)}%)`
+ : '';
+ return `${delta > 0 ? '+' : ''}${sizeText(delta)}${percent}`;
+}
+
+/** Why a comparison has no base, as the report says it. */
+const BASE_REASONS = {
+ 'no-merge-base':
+ "This branch's merge base with main is not within the fetched history (about 250 main commits).",
+ 'not-kept':
+ "Main's measurement of this pull request's merge base could not be found or read (main keeps one for 14 days, from when the measurement started).",
+};
+
+function fileCount(value) {
+ return isMeasured(value) ? String(num(value)) : 'N/A';
+}
+
+function changed(entry) {
+ if (!entry.base || !entry.head) return true;
+ return (
+ entry.base.packedBytes !== entry.head.packedBytes ||
+ entry.base.unpackedBytes !== entry.head.unpackedBytes ||
+ entry.base.files !== entry.head.files
+ );
+}
+
+/**
+ * The comparison as Markdown. `literal` renders a report string as inline
+ * text; the PR comment passes its own escaper, the job summary the identity.
+ */
+function renderPackageSizeSection(report, literal = text => String(text)) {
+ if (!report || !Array.isArray(report.packages)) return '';
+ const {packedPercent, packedMinBytes} = report.budget || {};
+ let out = '### Published Package Size\n\n';
+ if (report.verdict === 'no-base') {
+ out += `_${BASE_REASONS[report.baseReason] ?? BASE_REASONS['not-kept']} Only this head's sizes are shown, with no budget._\n\n`;
+ }
+ const rows =
+ report.verdict === 'no-base'
+ ? report.packages
+ : report.packages.filter(changed);
+ if (rows.length === 0) {
+ out += `No published package changed size (${num(report.packages.length)} measured).\n\n`;
+ } else {
+ out +=
+ '| Package | Download before | Download after | Delta | Unpacked before | Unpacked after | Delta | Files |\n';
+ out +=
+ '|---------|-----------------|----------------|-------|-----------------|----------------|-------|-------|\n';
+ for (const entry of rows) {
+ const files =
+ entry.base && entry.head && entry.base.files !== entry.head.files
+ ? `${fileCount(entry.base.files)} → ${fileCount(entry.head.files)}`
+ : fileCount(entry.head?.files ?? entry.base?.files);
+ out += `| ${literal(entry.name)} | ${sizeText(entry.base?.packedBytes)} | ${sizeText(entry.head?.packedBytes)} | ${deltaText(entry.head?.packedBytes, entry.base?.packedBytes)}${entry.overBudget ? ' ⚠️' : ''} | ${sizeText(entry.base?.unpackedBytes)} | ${sizeText(entry.head?.unpackedBytes)} | ${deltaText(entry.head?.unpackedBytes, entry.base?.unpackedBytes)} | ${files} |\n`;
+ }
+ const unchanged = report.packages.length - rows.length;
+ out +=
+ unchanged === 0
+ ? '\n'
+ : `\n${unchanged} other published ${unchanged === 1 ? 'package is' : 'packages are'} unchanged.\n\n`;
+ }
+ if (report.addedDependencies?.length > 0) {
+ out += '**New runtime dependencies:**\n\n';
+ for (const dependency of report.addedDependencies)
+ out += `- ${literal(dependency.package)}: ${literal(dependency.name)} ${literal(dependency.range)} (${literal(dependency.field)})\n`;
+ out += '\n';
+ }
+ if (report.removedDependencies?.length > 0) {
+ out += '**Removed runtime dependencies:**\n\n';
+ for (const dependency of report.removedDependencies)
+ out += `- ${literal(dependency.package)}: ${literal(dependency.name)} (${literal(dependency.field)})\n`;
+ out += '\n';
+ }
+ if (report.verdict === 'over-budget') {
+ out += `**⚠️ Over the package budget:** a package's download grew more than ${num(packedPercent)}% (and at least ${sizeText(num(packedMinBytes))}). If the growth is not intended, shrink it; if it is, say why in the pull request description.\n\n`;
+ }
+ out +=
+ 'Download is the gzip tarball npm fetches; unpacked is what lands in `node_modules`.\n\n';
+ return out;
+}
+
+module.exports = {
+ PACKED_BUDGET_PERCENT,
+ PACKED_BUDGET_MIN_BYTES,
+ publishedPackages,
+ runtimeDependencies,
+ measurePackages,
+ overBudget,
+ comparePackageSizes,
+ renderPackageSizeSection,
+};
diff --git a/.github/scripts/lib/package-size.test.mjs b/.github/scripts/lib/package-size.test.mjs
new file mode 100644
index 0000000000..6c4235ed25
--- /dev/null
+++ b/.github/scripts/lib/package-size.test.mjs
@@ -0,0 +1,422 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file package-size.test.mjs
+ * Pins the published-package-size check: which packages count as published,
+ * what `npm pack` measures, the advisory budget flag (a tarball growing more
+ * than 5% and at least 1 KB), the runtime-dependency diff, the Markdown, and
+ * the CLI, which flags and never fails.
+ */
+
+import {execFileSync, spawnSync} from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {afterEach, describe, expect, it} from 'vitest';
+import sizes from './package-size.js';
+
+const {
+ PACKED_BUDGET_MIN_BYTES,
+ publishedPackages,
+ measurePackages,
+ overBudget,
+ comparePackageSizes,
+ renderPackageSizeSection,
+} = sizes;
+
+const CLI = path.join(
+ path.dirname(fileURLToPath(import.meta.url)),
+ '..',
+ 'package-size.mjs',
+);
+
+const temporary = [];
+afterEach(() => {
+ for (const dir of temporary.splice(0))
+ fs.rmSync(dir, {recursive: true, force: true});
+});
+
+function tempDir() {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-package-size-'));
+ temporary.push(dir);
+ return dir;
+}
+
+function writePackage(root, relative, manifest, files = {}) {
+ const dir = path.join(root, relative);
+ fs.mkdirSync(dir, {recursive: true});
+ fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(manifest));
+ for (const [name, contents] of Object.entries(files)) {
+ fs.mkdirSync(path.dirname(path.join(dir, name)), {recursive: true});
+ fs.writeFileSync(path.join(dir, name), contents);
+ }
+ return dir;
+}
+
+function measurement(packages) {
+ return {schema: 1, packages};
+}
+
+function pkg(packedBytes, dependencies = {}, extra = {}) {
+ return {
+ packedBytes,
+ unpackedBytes: packedBytes * 4,
+ files: 10,
+ dependencies,
+ ...extra,
+ };
+}
+
+describe('publishedPackages', () => {
+ it('keeps public scoped packages and drops private, canary-only and unscoped ones', () => {
+ const root = tempDir();
+ writePackage(root, 'packages/core', {name: '@astryxdesign/core'});
+ writePackage(root, 'packages/themes/neutral', {
+ name: '@astryxdesign/theme-neutral',
+ });
+ writePackage(root, 'packages/lab', {
+ name: '@astryxdesign/lab',
+ private: true,
+ });
+ writePackage(root, 'packages/canary', {
+ name: '@astryxdesign/canary',
+ astryx: {canaryOnly: true},
+ });
+ writePackage(root, 'packages/other', {name: 'unscoped'});
+ expect(publishedPackages(root).map(entry => entry.manifest.name)).toEqual([
+ '@astryxdesign/core',
+ '@astryxdesign/theme-neutral',
+ ]);
+ });
+});
+
+describe('measurePackages', () => {
+ it('records npm pack sizes and runtime dependencies, not dev dependencies', async () => {
+ const root = tempDir();
+ writePackage(root, 'packages/core', {
+ name: '@astryxdesign/core',
+ dependencies: {'@stylexjs/stylex': '^0.19.0'},
+ peerDependencies: {react: '>=19'},
+ devDependencies: {vitest: '4'},
+ });
+ const result = await measurePackages(root, async () => ({
+ size: 100,
+ unpackedSize: 400,
+ entryCount: 3,
+ }));
+ expect(result.packages['@astryxdesign/core']).toEqual({
+ packedBytes: 100,
+ unpackedBytes: 400,
+ files: 3,
+ dependencies: {
+ 'dependencies:@stylexjs/stylex': '^0.19.0',
+ 'peerDependencies:react': '>=19',
+ },
+ });
+ });
+
+ it('measures a real package with npm pack, honouring files and skipping lifecycle scripts', async () => {
+ const root = tempDir();
+ writePackage(
+ root,
+ 'packages/core',
+ {
+ name: '@astryxdesign/core',
+ version: '0.0.0',
+ files: ['dist'],
+ scripts: {prepack: 'exit 1'},
+ },
+ {
+ 'dist/index.js': 'export const a = 1;\n'.repeat(200),
+ 'src/index.test.ts': 'not shipped',
+ },
+ );
+ const {packages} = await measurePackages(root);
+ const core = packages['@astryxdesign/core'];
+ // package.json and dist/index.js; the test file is outside `files`.
+ expect(core.files).toBe(2);
+ expect(core.unpackedBytes).toBeGreaterThan(4000);
+ expect(core.packedBytes).toBeGreaterThan(0);
+ expect(core.packedBytes).toBeLessThan(core.unpackedBytes);
+ });
+});
+
+describe('overBudget', () => {
+ it('needs more than 5% and at least the byte floor', () => {
+ const base = 100 * 1024;
+ expect(overBudget(base, base + 5 * 1024)).toBe(false); // exactly 5%
+ expect(overBudget(base, base + 5 * 1024 + 1)).toBe(true);
+ // 10% of a small package, but under the floor.
+ expect(overBudget(5000, 5000 + PACKED_BUDGET_MIN_BYTES - 1)).toBe(false);
+ expect(overBudget(5000, 5000 + PACKED_BUDGET_MIN_BYTES)).toBe(true);
+ });
+
+ it('never fires without both measurements', () => {
+ expect(overBudget(undefined, 999999)).toBe(false);
+ expect(overBudget(1000, null)).toBe(false);
+ expect(overBudget(0, 999999)).toBe(false);
+ });
+});
+
+describe('comparePackageSizes', () => {
+ const base = measurement({
+ '@astryxdesign/core': pkg(100_000, {
+ 'dependencies:@stylexjs/stylex': '^0.19.0',
+ }),
+ '@astryxdesign/theme-neutral': pkg(20_000),
+ });
+
+ it('passes an unchanged head', () => {
+ const report = comparePackageSizes({head: base, base});
+ expect(report.verdict).toBe('pass');
+ expect(report.packages.every(entry => !entry.overBudget)).toBe(true);
+ expect(report.addedDependencies).toEqual([]);
+ });
+
+ it('flags a package past the budget', () => {
+ const head = measurement({
+ ...base.packages,
+ '@astryxdesign/core': pkg(
+ 110_000,
+ base.packages['@astryxdesign/core'].dependencies,
+ ),
+ });
+ const flagged = comparePackageSizes({head, base});
+ expect(flagged.verdict).toBe('over-budget');
+ expect(
+ flagged.packages.find(entry => entry.name === '@astryxdesign/core')
+ .overBudget,
+ ).toBe(true);
+ });
+
+ it('lists added and removed runtime dependencies', () => {
+ const head = measurement({
+ '@astryxdesign/core': pkg(100_000, {'dependencies:lodash': '^4.17.21'}),
+ '@astryxdesign/theme-neutral': pkg(20_000),
+ });
+ const report = comparePackageSizes({head, base});
+ expect(report.addedDependencies).toEqual([
+ {
+ package: '@astryxdesign/core',
+ field: 'dependencies',
+ name: 'lodash',
+ range: '^4.17.21',
+ },
+ ]);
+ expect(report.removedDependencies).toEqual([
+ {
+ package: '@astryxdesign/core',
+ field: 'dependencies',
+ name: '@stylexjs/stylex',
+ range: '^0.19.0',
+ },
+ ]);
+ });
+
+ it('reports a newly published package without a budget, its dependencies as new', () => {
+ const head = measurement({
+ ...base.packages,
+ '@astryxdesign/new': pkg(50_000, {'peerDependencies:react': '>=19'}),
+ });
+ const report = comparePackageSizes({head, base});
+ const added = report.packages.find(
+ entry => entry.name === '@astryxdesign/new',
+ );
+ expect(added.base).toBeNull();
+ expect(added.overBudget).toBe(false);
+ expect(report.verdict).toBe('pass');
+ expect(report.addedDependencies).toEqual([
+ {
+ package: '@astryxdesign/new',
+ field: 'peerDependencies',
+ name: 'react',
+ range: '>=19',
+ },
+ ]);
+ });
+
+ it('applies no budget and diffs no dependencies without a base', () => {
+ const head = measurement({
+ '@astryxdesign/core': pkg(999_999, {'dependencies:x': '1'}),
+ });
+ const report = comparePackageSizes({head, base: null});
+ expect(report.verdict).toBe('no-base');
+ expect(report.addedDependencies).toEqual([]);
+ });
+});
+
+describe('renderPackageSizeSection', () => {
+ const base = measurement({
+ '@astryxdesign/core': pkg(100_000),
+ '@astryxdesign/theme-neutral': pkg(20_000),
+ '@astryxdesign/theme-stone': pkg(20_000),
+ });
+
+ it('shows only changed packages and counts the rest', () => {
+ const head = measurement({
+ ...base.packages,
+ '@astryxdesign/core': pkg(101_000),
+ });
+ const markdown = renderPackageSizeSection(
+ comparePackageSizes({head, base}),
+ );
+ expect(markdown).toContain('### Published Package Size');
+ expect(markdown).toContain(
+ '| @astryxdesign/core | 97.7KB | 98.6KB | +1000B (+1.0%) |',
+ );
+ expect(markdown).not.toContain('theme-neutral');
+ expect(markdown).toContain('2 other published packages are unchanged.');
+ expect(markdown).not.toContain('Over the package budget');
+ });
+
+ it('writes a package past 1 MB in MB', () => {
+ const big = measurement({'@astryxdesign/core': pkg(9_000_000)});
+ const markdown = renderPackageSizeSection(
+ comparePackageSizes({
+ head: measurement({'@astryxdesign/core': pkg(9_100_000)}),
+ base: big,
+ }),
+ );
+ expect(markdown).toContain(
+ '| @astryxdesign/core | 8.58MB | 8.68MB | +97.7KB (+1.1%) |',
+ );
+ });
+
+ it('says when nothing changed', () => {
+ const markdown = renderPackageSizeSection(
+ comparePackageSizes({head: base, base}),
+ );
+ expect(markdown).toContain(
+ 'No published package changed size (3 measured).',
+ );
+ });
+
+ it('flags the row and asks the author when over budget', () => {
+ const head = measurement({
+ ...base.packages,
+ '@astryxdesign/core': pkg(110_000),
+ });
+ const markdown = renderPackageSizeSection(
+ comparePackageSizes({head, base}),
+ );
+ expect(markdown).toMatch(
+ /\| @astryxdesign\/core \|[^\n]*\(\+10\.0%\) ⚠️ \|/,
+ );
+ expect(markdown).toContain('**⚠️ Over the package budget:**');
+ expect(markdown).toContain('say why in the pull request description');
+ });
+
+ it('shows every head size and no budget without a base', () => {
+ const markdown = renderPackageSizeSection(
+ comparePackageSizes({head: base, base: null}),
+ );
+ expect(markdown).toContain('with no budget');
+ expect(markdown).toContain('theme-stone');
+ });
+
+ it('renders report strings through the given escaper', () => {
+ const head = measurement({
+ '@astryxdesign/core': pkg(100_000, {'dependencies:<img src=x>': '1'}),
+ });
+ const markdown = renderPackageSizeSection(
+ comparePackageSizes({
+ head,
+ base: measurement({'@astryxdesign/core': pkg(100_000)}),
+ }),
+ text => `[${text}]`,
+ );
+ expect(markdown).toContain(
+ '- [@astryxdesign/core]: [<img src=x>] [1] ([dependencies])',
+ );
+ });
+});
+
+describe('package-size.mjs', () => {
+ function runCli(args) {
+ return spawnSync(process.execPath, [CLI, ...args], {encoding: 'utf8'});
+ }
+
+ function compare({head, base}) {
+ const dir = tempDir();
+ const file = name => path.join(dir, name);
+ fs.writeFileSync(file('head.json'), JSON.stringify(head));
+ if (base) fs.writeFileSync(file('base.json'), JSON.stringify(base));
+ const result = runCli([
+ 'compare',
+ '--head',
+ file('head.json'),
+ '--base',
+ file('base.json'),
+ '--head-sha',
+ 'a'.repeat(40),
+ '--output',
+ file('report.json'),
+ '--summary',
+ file('summary.md'),
+ ]);
+ return {
+ result,
+ report: JSON.parse(fs.readFileSync(file('report.json'), 'utf8')),
+ summary: fs.readFileSync(file('summary.md'), 'utf8'),
+ };
+ }
+
+ const base = measurement({'@astryxdesign/core': pkg(100_000)});
+ const grown = measurement({'@astryxdesign/core': pkg(110_000)});
+
+ it('flags an overrun with a warning and never fails', () => {
+ const {result, report, summary} = compare({head: grown, base});
+ expect(result.status).toBe(0);
+ expect(report.headSha).toBe('a'.repeat(40));
+ expect(summary).toContain('**⚠️ Over the package budget:**');
+ expect(result.stdout).toContain(
+ '::warning title=Package size over budget::',
+ );
+ expect(result.stdout).not.toContain('::error');
+ });
+
+ it.each([
+ ['no-merge-base', 'not within the fetched history'],
+ ['not-kept', 'could not be found or read'],
+ ])('names why there is no base: %s', (reason, text) => {
+ const report = comparePackageSizes({
+ head: grown,
+ base: null,
+ baseReason: reason,
+ });
+ expect(report.baseReason).toBe(reason);
+ expect(renderPackageSizeSection(report)).toContain(text);
+ });
+
+ it('compares without a base, with a notice and no flag', () => {
+ const {result, report} = compare({head: grown, base: null});
+ expect(result.status).toBe(0);
+ expect(report.verdict).toBe('no-base');
+ expect(result.stdout).toContain('::notice::');
+ expect(result.stdout).not.toContain('::warning');
+ });
+
+ it('measure writes every published package of a workspace', () => {
+ const root = tempDir();
+ writePackage(
+ root,
+ 'packages/core',
+ {name: '@astryxdesign/core', version: '0.0.0'},
+ {
+ 'index.js': 'export {};\n',
+ },
+ );
+ const output = path.join(root, 'out.json');
+ execFileSync(process.execPath, [
+ CLI,
+ 'measure',
+ '--root',
+ root,
+ '--output',
+ output,
+ ]);
+ const written = JSON.parse(fs.readFileSync(output, 'utf8'));
+ expect(Object.keys(written.packages)).toEqual(['@astryxdesign/core']);
+ });
+});
diff --git a/.github/scripts/lib/pr-preview.mjs b/.github/scripts/lib/pr-preview.mjs
index 6424e2899a..2c1880a2fd 100644
--- a/.github/scripts/lib/pr-preview.mjs
+++ b/.github/scripts/lib/pr-preview.mjs
@@ -477,18 +477,20 @@ function trustedAnalysis({analysisPath, metadataPath, identity, core}) {
* Base measurements come from the same CI run's merge-base build. They are
* used only when they name the exact head this comment reports.
*/
-function trustedBaseStats({baseStatsPath, identity, core}) {
+// A size report the generator may read: present and written for the exact
+// head being reported.
+function trustedHeadReport({reportPath, label, identity, core}) {
try {
- if (!fs.existsSync(baseStatsPath)) return false;
- const stats = readJSON(baseStatsPath);
+ if (!fs.existsSync(reportPath)) return false;
+ const report = readJSON(reportPath);
if (
- !FULL_SHA.test(String(stats.headSha)) ||
- stats.headSha !== identity.headSha
+ !FULL_SHA.test(String(report.headSha)) ||
+ report.headSha !== identity.headSha
)
- refuse('base stats head does not match');
+ refuse(`${label} head does not match`);
return true;
} catch (error) {
- core.warning(`Ignoring untrusted or stale base stats: ${error.message}`);
+ core.warning(`Ignoring untrusted or stale ${label}: ${error.message}`);
return false;
}
}
@@ -510,6 +512,7 @@ export async function reconcilePrComment({
analysisPath = 'pr-analysis/analysis.json',
metadataPath = 'pr-analysis/pr-meta.json',
baseStatsPath = 'pr-size-base/size-base.json',
+ packageSizePath = 'pr-analysis/package-size.json',
a11yPath = 'a11y/a11y-report.json',
visualPath = 'trusted-visual/verdict.json',
createIfMissing = true,
@@ -562,9 +565,22 @@ export async function reconcilePrComment({
generator,
'--analysis',
analysisPath,
- ...(trustedBaseStats({baseStatsPath, identity, core})
+ ...(trustedHeadReport({
+ reportPath: baseStatsPath,
+ label: 'base stats',
+ identity,
+ core,
+ })
? ['--base-stats', baseStatsPath]
: []),
+ ...(trustedHeadReport({
+ reportPath: packageSizePath,
+ label: 'package size report',
+ identity,
+ core,
+ })
+ ? ['--package-size', packageSizePath]
+ : []),
// No report means the audit did not run (it runs on main and release
// checks, or with the ci:run-a11y label); the comment says so.
...(fs.existsSync(a11yPath) ? ['--a11y', a11yPath] : []),
diff --git a/.github/scripts/lib/pr-preview.test.mjs b/.github/scripts/lib/pr-preview.test.mjs
index 9e89018876..c015c2b8bd 100644
--- a/.github/scripts/lib/pr-preview.test.mjs
+++ b/.github/scripts/lib/pr-preview.test.mjs
@@ -201,6 +201,7 @@ async function reconcile({
fallbackMessage,
execute,
baseStats,
+ packageSize,
} = {}) {
const value = previewAvailable
? {...requested, headRepository: requested.baseRepository}
@@ -212,6 +213,12 @@ async function reconcile({
'size-base.json',
);
if (baseStats) fs.writeFileSync(baseStatsPath, JSON.stringify(baseStats));
+ const packageSizePath = path.join(
+ path.dirname(paths.analysis),
+ 'package-size.json',
+ );
+ if (packageSize)
+ fs.writeFileSync(packageSizePath, JSON.stringify(packageSize));
const {github, state} = githubFixture({
value: githubFixtureValue,
comments,
@@ -228,6 +235,7 @@ async function reconcile({
analysisPath: paths.analysis,
metadataPath: paths.metadata,
baseStatsPath,
+ packageSizePath,
a11yPath: paths.a11y,
visualPath: paths.visual,
createIfMissing,
@@ -964,6 +972,25 @@ describe('PR comment preview reconciliation', () => {
},
);
+ it.each([
+ ['the exact head', HEAD, true],
+ ['another head', 'b'.repeat(40), false],
+ ])(
+ 'passes the package size report only when it names %s',
+ async (_label, headSha, used) => {
+ const seen = [];
+ await reconcile({
+ packageSize: {headSha, packages: [], verdict: 'pass'},
+ execute: (_node, args) => {
+ seen.push(args);
+ return '## PR Analysis Report\n';
+ },
+ });
+ expect(seen).toHaveLength(1);
+ expect(seen[0].includes('--package-size')).toBe(used);
+ },
+ );
+
it('falls back to a safe current message when analysis rendering fails', async () => {
const stale = {
id: 78,
diff --git a/.github/scripts/lib/report-text.js b/.github/scripts/lib/report-text.js
index ea18c9d646..111d929532 100644
--- a/.github/scripts/lib/report-text.js
+++ b/.github/scripts/lib/report-text.js
@@ -20,7 +20,7 @@ function inline(value) {
.replace(/&/g, '&amp;')
.replace(/</g, '&lt;')
.replace(/>/g, '&gt;')
- .replace(/[|[\]`*_~]/g, (ch) => `\\${ch}`);
+ .replace(/[|[\]`*_~]/g, ch => `\\${ch}`);
}
/** A finite number, or the fallback. */
@@ -39,4 +39,15 @@ function safeUrl(value) {
return /^https?:\/\/[^\s<>"'()\\]+$/.test(url) ? url : null;
}
-module.exports = {inline, num, safeUrl};
+/**
+ * A measured byte count as text (`900B`, `1.5KB`, `2.25MB`), or N/A. Shared by
+ * every size the PR report shows.
+ */
+function sizeText(bytes) {
+ if (typeof bytes !== 'number' || !Number.isFinite(bytes)) return 'N/A';
+ if (Math.abs(bytes) < 1024) return `${bytes}B`;
+ if (Math.abs(bytes) < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+ return `${(bytes / (1024 * 1024)).toFixed(2)}MB`;
+}
+
+module.exports = {inline, num, safeUrl, sizeText};
diff --git a/.github/scripts/merge-base.sh b/.github/scripts/merge-base.sh
new file mode 100755
index 0000000000..2d41d633b9
--- /dev/null
+++ b/.github/scripts/merge-base.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# Prints the pull request's merge base with origin/<base-ref>, deepening the
+# fetched history once when the shallow checkout does not reach it. Prints
+# nothing, with a workflow warning, when it still cannot find one. Shared by
+# the CI steps that compare a pull request with its merge base.
+#
+# usage: merge-base.sh <base-ref> <what the caller skips without one>
+set -uo pipefail
+base_ref="$1"
+skipped="$2"
+if ! sha=$(git merge-base "origin/$base_ref" HEAD 2>/dev/null); then
+ git fetch --deepen=200 origin "$base_ref:refs/remotes/origin/$base_ref" >/dev/null 2>&1 || true
+ if ! sha=$(git merge-base "origin/$base_ref" HEAD 2>/dev/null); then
+ echo "::warning::no merge base within the fetched history; skipping $skipped" >&2
+ exit 0
+ fi
+fi
+echo "$sha"
diff --git a/.github/scripts/merge-base.test.mjs b/.github/scripts/merge-base.test.mjs
new file mode 100644
index 0000000000..79dcaee68b
--- /dev/null
+++ b/.github/scripts/merge-base.test.mjs
@@ -0,0 +1,70 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file merge-base.test.mjs
+ * Pins merge-base.sh: it prints the merge base with origin/<base>, and
+ * prints nothing but a workflow warning naming what the caller skips when the
+ * history has none.
+ */
+
+import {execFileSync, spawnSync} from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {afterEach, describe, expect, it} from 'vitest';
+
+const SCRIPT = path.join(
+ path.dirname(fileURLToPath(import.meta.url)),
+ 'merge-base.sh',
+);
+const roots = [];
+afterEach(() => {
+ for (const root of roots.splice(0))
+ fs.rmSync(root, {recursive: true, force: true});
+});
+
+function repo() {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'merge-base-'));
+ roots.push(root);
+ const git = (...args) =>
+ execFileSync('git', args, {cwd: root, encoding: 'utf8'}).trim();
+ git('init', '-q', '-b', 'main');
+ git('config', 'user.email', '[email protected]');
+ git('config', 'user.name', 'Test');
+ git('commit', '-q', '--allow-empty', '-m', 'base');
+ return {root, git};
+}
+
+describe('merge-base.sh', () => {
+ it('prints the merge base with origin/<base>', () => {
+ const {root, git} = repo();
+ const base = git('rev-parse', 'HEAD');
+ git('update-ref', 'refs/remotes/origin/main', base);
+ git('checkout', '-q', '-b', 'feature');
+ git('commit', '-q', '--allow-empty', '-m', 'change');
+ const result = spawnSync('bash', [SCRIPT, 'main', 'the check'], {
+ cwd: root,
+ encoding: 'utf8',
+ });
+ expect(result.status).toBe(0);
+ expect(result.stdout.trim()).toBe(base);
+ });
+
+ it('prints nothing and warns when there is no merge base', () => {
+ const {root} = repo();
+ const result = spawnSync(
+ 'bash',
+ [SCRIPT, 'main', 'the package-size comparison'],
+ {
+ cwd: root,
+ encoding: 'utf8',
+ },
+ );
+ expect(result.status).toBe(0);
+ expect(result.stdout).toBe('');
+ expect(result.stderr).toContain(
+ '::warning::no merge base within the fetched history; skipping the package-size comparison',
+ );
+ });
+});
diff --git a/.github/scripts/package-size.mjs b/.github/scripts/package-size.mjs
new file mode 100644
index 0000000000..408ddd0859
--- /dev/null
+++ b/.github/scripts/package-size.mjs
@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Published package size: measure a built workspace, or compare a pull
+ * request's measurement with its merge base's.
+ * @input `measure --output <file> [--root <dir>]`: a workspace whose packages
+ * are built.
+ * `compare --head <file> [--base <file>] --output <file>
+ * [--summary <file>] [--head-sha <sha>] [--base-sha <sha>]
+ * [--base-reason no-merge-base|not-kept]`: two measurements (a missing or
+ * unreadable base compares nothing, and the reason says why).
+ * @output `measure` writes each published package's sizes and runtime
+ * dependencies. `compare` writes the comparison, appends it to the job
+ * summary, and flags (never fails) a package over its budget.
+ * @position CI's build-storybook job measures and compares a pull request's
+ * head; Main's typecheck job measures each main commit and keeps it for 14
+ * days as the base. The PR report renders the comparison.
+ */
+
+import fs from 'node:fs';
+import {createRequire} from 'node:module';
+
+const require = createRequire(import.meta.url);
+const {
+ measurePackages,
+ comparePackageSizes,
+ renderPackageSizeSection,
+} = require('./lib/package-size.js');
+
+const [command, ...args] = process.argv.slice(2);
+const getArg = name => {
+ const index = args.indexOf(`--${name}`);
+ return index !== -1 ? args[index + 1] : null;
+};
+
+function readJson(file) {
+ if (!file) return null;
+ try {
+ return JSON.parse(fs.readFileSync(file, 'utf8'));
+ } catch {
+ return null;
+ }
+}
+
+if (command === 'measure') {
+ const output = getArg('output');
+ if (!output) throw new Error('measure needs --output <file>');
+ const measurement = await measurePackages(getArg('root') || process.cwd());
+ fs.writeFileSync(output, `${JSON.stringify(measurement, null, 2)}\n`);
+ console.log(
+ `Measured ${Object.keys(measurement.packages).length} published packages.`,
+ );
+} else if (command === 'compare') {
+ const output = getArg('output');
+ const head = readJson(getArg('head'));
+ if (!output || !head)
+ throw new Error('compare needs --head <file> and --output <file>');
+ const base = readJson(getArg('base'));
+ if (getArg('base') && !base)
+ console.log(
+ '::notice::No base measurement for the merge base; sizes are shown without a budget.',
+ );
+ const report = comparePackageSizes({
+ head,
+ base,
+ headSha: getArg('head-sha') || '',
+ baseSha: getArg('base-sha') || '',
+ baseReason: getArg('base-reason') || '',
+ });
+ fs.writeFileSync(output, `${JSON.stringify(report, null, 2)}\n`);
+ const markdown = renderPackageSizeSection(report);
+ const summary = getArg('summary');
+ if (summary) fs.appendFileSync(summary, markdown);
+ console.log(markdown);
+ if (report.verdict === 'over-budget')
+ console.log(
+ '::warning title=Package size over budget::A published package grew past its advisory budget. If the growth is not intended, shrink it; if it is, say why in the pull request description.',
+ );
+} else {
+ console.error(
+ 'usage: package-size.mjs measure --output <file> | compare --head <file> [--base <file>] --output <file>',
+ );
+ process.exitCode = 2;
+}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 885ee277f4..8f5db03721 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -924,6 +924,8 @@ jobs:
runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '4-core-ubuntu' || 'ubuntu-latest' }}
timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}
permissions:
+ # actions: read finds Main's kept package-size measurement of the merge base.
+ actions: read
contents: read
pull-requests: read
outputs:
@@ -943,6 +945,12 @@ jobs:
- name: Decide this job's scope
id: scope
uses: ./.test-scope/.github/actions/test-scope
+ with:
+ # `touches` scopes only the package-size check (a package, the
+ # lockfile, the root build inputs, or the check itself; shared
+ # infrastructure, `full_suite`, runs it too); the build itself
+ # follows the specialized-lane outputs.
+ paths: '^(packages/|pnpm-lock\.yaml$|package\.json$|tsconfig\.json$|scripts/|\.github/workflows/ci\.yml$|\.github/scripts/package-size\.mjs$|\.github/scripts/lib/package-size\.js$|\.github/scripts/merge-base\.sh$)'
- name: Skip heavy work for a specialized lane
if: steps.scope.outputs.docsite_only == 'true' || steps.scope.outputs.spec_only == 'true' || steps.scope.outputs.tooling_only == 'true'
@@ -1068,6 +1076,69 @@ jobs:
--output analysis.json \
"${FORCE_FULL[@]}"
+ # Published package size: this head's packages are built above, and Main
+ # keeps each main commit's measurement for 14 days, so the merge base is
+ # compared without building it. Only a pull request that changes a
+ # package or the lockfile runs it.
+ - name: Measure published package size
+ id: package-size
+ if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request' && (steps.scope.outputs.touches == 'true' || steps.scope.outputs.full_suite != 'false')
+ run: node .github/scripts/package-size.mjs measure --output package-size-head.json
+
+ - name: Find the merge base for package size
+ id: package-size-merge-base
+ if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.package-size.outcome == 'success'
+ env:
+ BASE_REF: ${{ github.base_ref }}
+ run: echo "sha=$(.github/scripts/merge-base.sh "$BASE_REF" 'the package-size comparison')" >> "$GITHUB_OUTPUT"
+
+ - name: Find main's package size for the merge base
+ id: package-size-cached
+ if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.package-size-merge-base.outputs.sha != ''
+ continue-on-error: true
+ uses: actions/github-script@v9
+ env:
+ BASE_SHA: ${{ steps.package-size-merge-base.outputs.sha }}
+ with:
+ retries: 3
+ script: |
+ const {mainArtifactRunId} = require(`${process.env.GITHUB_WORKSPACE}/.github/scripts/lib/main-artifact.cjs`);
+ const name = `package-size-main-${process.env.BASE_SHA}`;
+ const runId = await mainArtifactRunId({github, ...context.repo, name, sha: process.env.BASE_SHA});
+ core.setOutput('run_id', runId ?? '');
+ core.info(runId ? `Using ${name} from run ${runId}.` : `No ${name}; sizes are shown without a budget.`);
+
+ - name: Download main's package size for the merge base
+ if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.package-size-cached.outputs.run_id != ''
+ continue-on-error: true
+ uses: actions/download-artifact@v8
+ with:
+ name: package-size-main-${{ steps.package-size-merge-base.outputs.sha }}
+ run-id: ${{ steps.package-size-cached.outputs.run_id }}
+ github-token: ${{ github.token }}
+ path: .package-size-base
+
+ # Advisory: a package over its budget is flagged in the job summary and
+ # the PR report, and fails nothing.
+ - name: Compare published package size
+ if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.package-size.outcome == 'success'
+ env:
+ HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+ BASE_SHA: ${{ steps.package-size-merge-base.outputs.sha }}
+ run: |
+ # Without a base, the report names why: no merge base was found, or
+ # Main kept (or the lookup read) no measurement for it.
+ BASE_REASON=not-kept
+ if [ -z "$BASE_SHA" ]; then BASE_REASON=no-merge-base; fi
+ node .github/scripts/package-size.mjs compare \
+ --head package-size-head.json \
+ --base .package-size-base/package-size.json \
+ --base-reason "$BASE_REASON" \
+ --head-sha "$HEAD_SHA" \
+ --base-sha "$BASE_SHA" \
+ --output package-size.json \
+ --summary "$GITHUB_STEP_SUMMARY"
+
- name: Write PR comment metadata
if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request'
run: |
@@ -1094,6 +1165,7 @@ jobs:
path: |
analysis.json
pr-meta.json
+ package-size.json
retention-days: 1
# Measures the PR's merge base so the PR comment can show component and
@@ -1147,13 +1219,10 @@ jobs:
env:
BASE_REF: ${{ github.base_ref }}
run: |
- if ! BASE_SHA=$(git merge-base "origin/$BASE_REF" HEAD); then
- git fetch --deepen=200 origin "$BASE_REF:refs/remotes/origin/$BASE_REF" || true
- if ! BASE_SHA=$(git merge-base "origin/$BASE_REF" HEAD); then
- echo "::warning::no merge base within the fetched history; skipping base size measurement"
- echo "found=false" >> "$GITHUB_OUTPUT"
- exit 0
- fi
+ BASE_SHA=$(.github/scripts/merge-base.sh "$BASE_REF" 'base size measurement' || true)
+ if [ -z "$BASE_SHA" ]; then
+ echo "found=false" >> "$GITHUB_OUTPUT"
+ exit 0
fi
git worktree add --detach .size-base "$BASE_SHA"
echo "sha=$BASE_SHA" >> "$GITHUB_OUTPUT"
@@ -1178,17 +1247,11 @@ jobs:
with:
retries: 3
script: |
+ const {mainArtifactRunId} = require(`${process.env.GITHUB_WORKSPACE}/.github/scripts/lib/main-artifact.cjs`);
const name = `dists-main-${process.env.BASE_SHA}`;
- const {data} = await github.rest.actions.listArtifactsForRepo({...context.repo, name, per_page: 100});
- // Only Main's own run on main for this exact commit: a pull
- // request's run can upload an artifact under any name.
- const artifact = data.artifacts.find(candidate =>
- !candidate.expired &&
- candidate.workflow_run?.head_branch === 'main' &&
- candidate.workflow_run?.head_sha === process.env.BASE_SHA &&
- candidate.workflow_run?.head_repository_id === candidate.workflow_run?.repository_id);
- core.setOutput('run_id', artifact ? String(artifact.workflow_run.id) : '');
- core.info(artifact ? `Using ${name} from run ${artifact.workflow_run.id}.` : `No ${name}; building the merge base.`);
+ const runId = await mainArtifactRunId({github, ...context.repo, name, sha: process.env.BASE_SHA});
+ core.setOutput('run_id', runId ?? '');
+ core.info(runId ? `Using ${name} from run ${runId}.` : `No ${name}; building the merge base.`);
- name: Download main's build of the merge base
id: download
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 5f93ce343e..a65af1395c 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -142,6 +142,18 @@ jobs:
packages/themes/*/dist/
retention-days: 14
+ # A pull request compares its published package sizes with its merge
+ # base's from this measurement (ci.yml build-storybook).
+ - name: Measure published package size
+ run: node .github/scripts/package-size.mjs measure --output package-size.json
+
+ - name: Keep this commit's package size for PR size reports
+ uses: actions/upload-artifact@v7
+ with:
+ name: package-size-main-${{ needs.main-commit.outputs.sha }}
+ path: package-size.json
+ retention-days: 14
+
- name: Verify package exports
run: node scripts/verify-exports.mjs