From e044544039337a0c16638dd586bd1eaf62fae190 Mon Sep 17 00:00:00 2001 From: IEvangelist <7679720+IEvangelist@users.noreply.github.com> Date: Wed, 18 Nov 2026 16:00:46 -0600 Subject: [PATCH 1/2] Report frontend dist size and soft budget on every build Measure dist (total/HTML bytes, file and page counts, median page, top-level and reference/api directories) in every frontend build, write it to the job summary, and warn when it exceeds FRONTEND_DIST_BUDGET_BYTES (default 10 GiB). Set FRONTEND_DIST_BUDGET_MODE=error to fail instead. The file manifest and compression sample remain opt-in profiling diagnostics. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/frontend-build.yml | 10 +- src/frontend/scripts/measure-build-output.mjs | 203 +++++++++++++----- .../unit/build-performance.vitest.test.ts | 57 ++++- 3 files changed, 219 insertions(+), 51 deletions(-) diff --git a/.github/workflows/frontend-build.yml b/.github/workflows/frontend-build.yml index b5b811da58..7cf969438d 100644 --- a/.github/workflows/frontend-build.yml +++ b/.github/workflows/frontend-build.yml @@ -168,12 +168,20 @@ jobs: echo "- Size: \`$(du -sh node_modules/.astro 2>/dev/null | cut -f1)\`" } >> "$GITHUB_STEP_SUMMARY" + # Every build reports dist size (total, HTML, counts, median page, + # top-level and reference/api directories) to the job summary and + # checks it against a soft budget. Tune it with the repository + # variables FRONTEND_DIST_BUDGET_BYTES and FRONTEND_DIST_BUDGET_MODE + # (`warn`, the default, or `error` to fail the build when exceeded). + # The file manifest and compression sample remain opt-in profiling. - name: Measure frontend output - if: ${{ inputs.profile_build }} + if: ${{ !cancelled() && hashFiles('src/frontend/dist/index.html') != '' }} env: BUILD_METRICS_DIR: ${{ runner.temp }}/frontend-performance ASTRO_CACHE_HIT: ${{ steps.astro_cache.outputs.cache-matched-key != '' }} PROFILE_BUILD: ${{ inputs.profile_build }} + DIST_SIZE_BUDGET_BYTES: ${{ vars.FRONTEND_DIST_BUDGET_BYTES }} + DIST_SIZE_BUDGET_MODE: ${{ vars.FRONTEND_DIST_BUDGET_MODE }} run: node scripts/measure-build-output.mjs - name: Upload build diagnostics diff --git a/src/frontend/scripts/measure-build-output.mjs b/src/frontend/scripts/measure-build-output.mjs index 58d93c6499..77529a5d60 100644 --- a/src/frontend/scripts/measure-build-output.mjs +++ b/src/frontend/scripts/measure-build-output.mjs @@ -7,28 +7,32 @@ import { gzip } from 'node:zlib'; const compress = promisify(gzip); +// Slightly above the measured main baseline (~9.8 GB of dist), so the budget +// reports without firing until the output grows. Override with +// DIST_SIZE_BUDGET_BYTES; set DIST_SIZE_BUDGET_MODE=error to fail the build. +export const DEFAULT_DIST_SIZE_BUDGET_BYTES = 10 * 1024 ** 3; + export function outputGroup(path) { if (path.startsWith('reference/api/')) return path.split('/').slice(0, 3).join('/'); return path.includes('/') ? path.split('/')[0] : '(root)'; } -export async function measureOutput(directory) { - /** @type {{ path: string, bytes: number }[]} */ - const files = []; - async function walk(relative = '') { - const entries = await readdir(join(directory, relative), { withFileTypes: true }); - for (const entry of entries) { - const path = relative ? `${relative}/${entry.name}` : entry.name; - if (entry.isDirectory()) await walk(path); - else if (entry.isFile()) files.push({ path, bytes: (await stat(join(directory, path))).size }); - } - } - await walk(); - files.sort((a, b) => a.path.localeCompare(b.path)); +export function topLevelGroup(path) { + return path.includes('/') ? path.split('/')[0] : '(root)'; +} + +function median(values) { + if (values.length === 0) return 0; + const sorted = [...values].sort((a, b) => a - b); + const middle = Math.floor(sorted.length / 2); + return sorted.length % 2 ? sorted[middle] : Math.round((sorted[middle - 1] + sorted[middle]) / 2); +} + +function groupFiles(files, keyOf) { /** @type {Map} */ const groups = new Map(); for (const file of files) { - const key = outputGroup(file.path); + const key = keyOf(file.path); const group = groups.get(key) ?? { path: key, files: 0, bytes: 0, htmlFiles: 0, markdownFiles: 0 }; group.files++; group.bytes += file.bytes; @@ -36,13 +40,110 @@ export async function measureOutput(directory) { if (file.path.endsWith('.md')) group.markdownFiles++; groups.set(key, group); } + return [...groups.values()].sort((a, b) => b.bytes - a.bytes || a.path.localeCompare(b.path)); +} + +export async function measureOutput(directory) { + /** @type {{ path: string, bytes: number }[]} */ + const files = []; + // dist holds ~80k files: stat each directory's entries concurrently (libuv + // bounds the real parallelism) instead of awaiting them one at a time. + async function walk(relative = '') { + const entries = await readdir(join(directory, relative), { withFileTypes: true }); + await Promise.all(entries.map(async (entry) => { + const path = relative ? `${relative}/${entry.name}` : entry.name; + if (entry.isDirectory()) await walk(path); + else if (entry.isFile()) files.push({ path, bytes: (await stat(join(directory, path))).size }); + })); + } + await walk(); + files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)); + const htmlSizes = files.filter((file) => file.path.endsWith('.html')).map((file) => file.bytes); return { files, totalBytes: files.reduce((sum, file) => sum + file.bytes, 0), - groups: [...groups.values()].sort((a, b) => b.bytes - a.bytes), + htmlFiles: htmlSizes.length, + htmlBytes: htmlSizes.reduce((sum, bytes) => sum + bytes, 0), + medianHtmlBytes: median(htmlSizes), + groups: groupFiles(files, outputGroup), + topLevel: groupFiles(files, topLevelGroup), + }; +} + +export function readBudget(env = process.env) { + const raw = env.DIST_SIZE_BUDGET_BYTES?.trim(); + const bytes = raw ? Number(raw) : DEFAULT_DIST_SIZE_BUDGET_BYTES; + if (!Number.isSafeInteger(bytes) || bytes <= 0) { + throw new Error(`DIST_SIZE_BUDGET_BYTES must be a positive integer, got '${raw}'.`); + } + const mode = (env.DIST_SIZE_BUDGET_MODE?.trim() || 'warn').toLowerCase(); + if (mode !== 'warn' && mode !== 'error') { + throw new Error(`DIST_SIZE_BUDGET_MODE must be 'warn' or 'error', got '${mode}'.`); + } + return { bytes, mode }; +} + +export function checkBudget(totalBytes, budget) { + const exceeded = totalBytes > budget.bytes; + const message = `dist is ${formatBytes(totalBytes)} (${totalBytes} bytes), ` + + `${exceeded ? 'over' : 'within'} the ${formatBytes(budget.bytes)} budget (${budget.bytes} bytes).`; + return { + exceeded, + message, + annotation: exceeded ? `::${budget.mode === 'error' ? 'error' : 'warning'} title=Frontend dist size budget::${message}` : undefined, + fail: exceeded && budget.mode === 'error', }; } +export function formatBytes(bytes) { + const units = ['B', 'KiB', 'MiB', 'GiB', 'TiB']; + let value = bytes; + let unit = 0; + while (value >= 1024 && unit < units.length - 1) { + value /= 1024; + unit++; + } + return unit === 0 ? `${value} B` : `${value.toFixed(value >= 100 ? 0 : value >= 10 ? 1 : 2)} ${units[unit]}`; +} + +export function formatSizeReport(output, budget, result) { + const row = (group) => `| \`${group.path}\` | ${formatBytes(group.bytes)} | ` + + `${(group.bytes / (output.totalBytes || 1) * 100).toFixed(1)}% | ${group.files} | ${group.htmlFiles} |`; + const apiGroups = output.groups.filter((group) => group.path.startsWith('reference/api/')); + const header = ['| Directory | Size | Share | Files | HTML pages |', '| --- | ---: | ---: | ---: | ---: |']; + return [ + '## Frontend dist size', + '', + `${result.exceeded ? (budget.mode === 'error' ? '❌' : '⚠️') : '✅'} ${result.message}`, + '', + '| Metric | Value |', + '| --- | ---: |', + `| Total size | ${formatBytes(output.totalBytes)} (${output.totalBytes} bytes) |`, + `| HTML size | ${formatBytes(output.htmlBytes)} |`, + `| Files | ${output.files.length} |`, + `| HTML pages | ${output.htmlFiles} |`, + `| Median HTML page | ${formatBytes(output.medianHtmlBytes)} |`, + `| Budget (${budget.mode}) | ${formatBytes(budget.bytes)} |`, + '', + '
Top-level directories (locale folders included)', + '', + ...header, + ...output.topLevel.map(row), + '', + '
', + '', + ...(apiGroups.length ? [ + '
reference/api by language', + '', + ...header, + ...apiGroups.map(row), + '', + '
', + '', + ] : []), + ].join('\n'); +} + export async function sampleCompression(directory, files) { // Stratify by output directory; cap this diagnostic so profiling doesn't re-compress dist. const selected = []; @@ -72,43 +173,49 @@ export async function sampleCompression(directory, files) { } async function main() { - const out = process.env.BUILD_METRICS_DIR; - if (!out) throw new Error('BUILD_METRICS_DIR is required.'); - await mkdir(out, { recursive: true }); + const budget = readBudget(); const output = await measureOutput(resolve('dist')); - const summary = { - commit: process.env.GITHUB_SHA, - run: process.env.GITHUB_RUN_ID, - attempt: process.env.GITHUB_RUN_ATTEMPT, - node: process.version, - runner: process.env.RUNNER_NAME, - runnerImage: process.env.ImageVersion, - contentCacheHit: process.env.ASTRO_CACHE_HIT === 'true', - lockfileSha256: createHash('sha256').update(await readFile('bun.lock')).digest('hex'), - fileCount: output.files.length, - totalBytes: output.totalBytes, - directories: output.groups, - largestFiles: [...output.files].sort((a, b) => b.bytes - a.bytes).slice(0, 20), - }; - await writeFile(join(out, 'output.json'), JSON.stringify(summary, null, 2)); - await writeFile(join(out, 'file-manifest.json'), JSON.stringify(output.files)); - if (process.env.PROFILE_BUILD === 'true') { - await writeFile(join(out, 'compression-sample.json'), - JSON.stringify(await sampleCompression(resolve('dist'), output.files), null, 2)); - } + const result = checkBudget(output.totalBytes, budget); if (process.env.GITHUB_STEP_SUMMARY) { - await appendFile(process.env.GITHUB_STEP_SUMMARY, [ - '## Frontend build measurements', - '', - `- ${summary.fileCount} output files; ${(summary.totalBytes / 1024 / 1024).toFixed(1)} MiB before artifact compression.`, - '- Phase timing, HTML/Markdown counts, largest directories/files, and output manifest: `frontend-performance` artifact.', - '- Concurrent Astro route logs can interleave paths and durations; they are not used for timing attribution.', - '', - ].join('\n')); + await appendFile(process.env.GITHUB_STEP_SUMMARY, formatSizeReport(output, budget, result)); } - console.log(`[build-output] ${summary.fileCount} files, ${summary.totalBytes} bytes`); + + const out = process.env.BUILD_METRICS_DIR; + if (out) { + await mkdir(out, { recursive: true }); + const summary = { + commit: process.env.GITHUB_SHA, + run: process.env.GITHUB_RUN_ID, + attempt: process.env.GITHUB_RUN_ATTEMPT, + node: process.version, + runner: process.env.RUNNER_NAME, + runnerImage: process.env.ImageVersion, + contentCacheHit: process.env.ASTRO_CACHE_HIT === 'true', + lockfileSha256: createHash('sha256').update(await readFile('bun.lock')).digest('hex'), + fileCount: output.files.length, + totalBytes: output.totalBytes, + htmlFiles: output.htmlFiles, + htmlBytes: output.htmlBytes, + medianHtmlBytes: output.medianHtmlBytes, + budget: { ...budget, exceeded: result.exceeded }, + topLevel: output.topLevel, + directories: output.groups, + largestFiles: [...output.files].sort((a, b) => b.bytes - a.bytes).slice(0, 20), + }; + await writeFile(join(out, 'output.json'), JSON.stringify(summary, null, 2)); + if (process.env.PROFILE_BUILD === 'true') { + await writeFile(join(out, 'file-manifest.json'), JSON.stringify(output.files)); + await writeFile(join(out, 'compression-sample.json'), + JSON.stringify(await sampleCompression(resolve('dist'), output.files), null, 2)); + } + } + + console.log(`[build-output] ${output.files.length} files, ${output.totalBytes} bytes, ` + + `${output.htmlFiles} HTML pages (median ${output.medianHtmlBytes} bytes)`); + if (result.annotation) console.log(result.annotation); + if (result.fail) process.exitCode = 1; } if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) { await main(); -} +} \ No newline at end of file diff --git a/src/frontend/tests/unit/build-performance.vitest.test.ts b/src/frontend/tests/unit/build-performance.vitest.test.ts index 8f93010df6..0a47aa0c6e 100644 --- a/src/frontend/tests/unit/build-performance.vitest.test.ts +++ b/src/frontend/tests/unit/build-performance.vitest.test.ts @@ -2,7 +2,14 @@ import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { afterEach, expect, test, vi } from 'vitest'; -import { measureOutput, sampleCompression } from '../../scripts/measure-build-output.mjs'; +import { + checkBudget, + DEFAULT_DIST_SIZE_BUDGET_BYTES, + formatSizeReport, + measureOutput, + readBudget, + sampleCompression, +} from '../../scripts/measure-build-output.mjs'; import buildTiming from '../../config/build-timing.mjs'; const directories: string[] = []; @@ -107,10 +114,56 @@ test('CPU, timing, output inventories and diagnostic uploads are opt-in only', a expect(workflow).toContain("BUILD_TIMING: ${{ inputs.profile_build && '1' || '0' }}"); expect(workflow).toMatch(/if \[\[ "\$PROFILE_BUILD" == "true" \]\]; then\n\s+mkdir -p/); expect(workflow).toMatch(/else\n\s+bun run build:production\n\s+fi/); - expect(workflow).toContain('name: Measure frontend output\n if: ${{ inputs.profile_build }}'); expect(workflow).toContain('name: Upload build diagnostics\n if: ${{ always() && inputs.profile_build }}'); }); +test('every build measures dist against a configurable size budget', async () => { + const workflow = (await readFile(new URL('../../../../.github/workflows/frontend-build.yml', import.meta.url), 'utf8')).replace(/\r\n/g, '\n'); + const measureStep = workflow.match(/- name: Measure frontend output\n([\s\S]*?)(?=\n {6}- name:)/)?.[1]; + expect(measureStep).toBeDefined(); + expect(measureStep).toContain("if: ${{ !cancelled() && hashFiles('src/frontend/dist/index.html') != '' }}"); + expect(measureStep).toContain('DIST_SIZE_BUDGET_BYTES: ${{ vars.FRONTEND_DIST_BUDGET_BYTES }}'); + expect(measureStep).toContain('DIST_SIZE_BUDGET_MODE: ${{ vars.FRONTEND_DIST_BUDGET_MODE }}'); +}); + +test('size report covers HTML, top-level and API directories', async () => { + const directory = await mkdtemp(join(tmpdir(), 'aspire-output-report-')); + directories.push(directory); + await mkdir(join(directory, 'ja', 'get-started'), { recursive: true }); + await mkdir(join(directory, 'reference', 'api', 'csharp'), { recursive: true }); + await writeFile(join(directory, 'index.html'), 'a'.repeat(10)); + await writeFile(join(directory, 'ja', 'get-started', 'index.html'), 'a'.repeat(30)); + await writeFile(join(directory, 'reference', 'api', 'csharp', 'index.html'), 'a'.repeat(100)); + await writeFile(join(directory, 'reference', 'api', 'csharp', 'type.md'), 'a'.repeat(5)); + await writeFile(join(directory, 'reference', 'index.html'), 'a'.repeat(20)); + const output = await measureOutput(directory); + expect(output).toMatchObject({ totalBytes: 165, htmlFiles: 4, htmlBytes: 160, medianHtmlBytes: 25 }); + expect(output.topLevel.map(({ path, bytes }) => [path, bytes])).toEqual([ + ['reference', 125], ['ja', 30], ['(root)', 10], + ]); + const budget = readBudget({}); + const report = formatSizeReport(output, budget, checkBudget(output.totalBytes, budget)); + expect(report).toContain('| HTML pages | 4 |'); + expect(report).toContain('| Median HTML page | 25 B |'); + expect(report).toContain('| `ja` | 30 B | 18.2% | 1 | 1 |'); + expect(report).toContain('| `reference/api/csharp` | 105 B |'); +}); + +test('size budget defaults to warning and can be switched to a hard failure', () => { + expect(readBudget({})).toEqual({ bytes: DEFAULT_DIST_SIZE_BUDGET_BYTES, mode: 'warn' }); + expect(readBudget({ DIST_SIZE_BUDGET_BYTES: '', DIST_SIZE_BUDGET_MODE: '' }).mode).toBe('warn'); + expect(() => readBudget({ DIST_SIZE_BUDGET_BYTES: '10GB' })).toThrow(/positive integer/); + expect(() => readBudget({ DIST_SIZE_BUDGET_MODE: 'fail' })).toThrow(/'warn' or 'error'/); + + expect(checkBudget(100, { bytes: 100, mode: 'warn' })).toMatchObject({ exceeded: false, fail: false, annotation: undefined }); + const warn = checkBudget(101, { bytes: 100, mode: 'warn' }); + expect(warn).toMatchObject({ exceeded: true, fail: false }); + expect(warn.annotation).toMatch(/^::warning title=Frontend dist size budget::/); + const error = checkBudget(101, readBudget({ DIST_SIZE_BUDGET_BYTES: '100', DIST_SIZE_BUDGET_MODE: 'error' })); + expect(error).toMatchObject({ exceeded: true, fail: true }); + expect(error.annotation).toMatch(/^::error /); +}); + test('Astro build source does not receive workflow credentials', async () => { const workflow = (await readFile(new URL('../../../../.github/workflows/frontend-build.yml', import.meta.url), 'utf8')).replace(/\r\n/g, '\n'); const buildStep = workflow.match(/- name: Build frontend\n([\s\S]*?)(?=\n {6}- name:)/)?.[1]; From 66928337b956b87ce1c13a7a86fcc7002a019fdc Mon Sep 17 00:00:00 2001 From: IEvangelist <7679720+IEvangelist@users.noreply.github.com> Date: Thu, 19 Nov 2026 11:40:44 -0600 Subject: [PATCH 2/2] Fall back to budget defaults when repo variables are invalid Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- src/frontend/scripts/measure-build-output.mjs | 13 ++++++++----- .../tests/unit/build-performance.vitest.test.ts | 7 +++++-- 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/src/frontend/scripts/measure-build-output.mjs b/src/frontend/scripts/measure-build-output.mjs index 77529a5d60..7cc5397378 100644 --- a/src/frontend/scripts/measure-build-output.mjs +++ b/src/frontend/scripts/measure-build-output.mjs @@ -70,15 +70,18 @@ export async function measureOutput(directory) { }; } -export function readBudget(env = process.env) { +export function readBudget(env = process.env, warn = (message) => console.log(`::warning title=Frontend dist size budget::${message}`)) { + // A mistyped repository variable must not fail the build: fall back to the defaults. const raw = env.DIST_SIZE_BUDGET_BYTES?.trim(); - const bytes = raw ? Number(raw) : DEFAULT_DIST_SIZE_BUDGET_BYTES; + let bytes = raw ? Number(raw) : DEFAULT_DIST_SIZE_BUDGET_BYTES; if (!Number.isSafeInteger(bytes) || bytes <= 0) { - throw new Error(`DIST_SIZE_BUDGET_BYTES must be a positive integer, got '${raw}'.`); + warn(`DIST_SIZE_BUDGET_BYTES must be a positive integer, got '${raw}'; using ${DEFAULT_DIST_SIZE_BUDGET_BYTES}.`); + bytes = DEFAULT_DIST_SIZE_BUDGET_BYTES; } - const mode = (env.DIST_SIZE_BUDGET_MODE?.trim() || 'warn').toLowerCase(); + let mode = (env.DIST_SIZE_BUDGET_MODE?.trim() || 'warn').toLowerCase(); if (mode !== 'warn' && mode !== 'error') { - throw new Error(`DIST_SIZE_BUDGET_MODE must be 'warn' or 'error', got '${mode}'.`); + warn(`DIST_SIZE_BUDGET_MODE must be 'warn' or 'error', got '${mode}'; using 'warn'.`); + mode = 'warn'; } return { bytes, mode }; } diff --git a/src/frontend/tests/unit/build-performance.vitest.test.ts b/src/frontend/tests/unit/build-performance.vitest.test.ts index 0a47aa0c6e..904eb4aff9 100644 --- a/src/frontend/tests/unit/build-performance.vitest.test.ts +++ b/src/frontend/tests/unit/build-performance.vitest.test.ts @@ -152,8 +152,11 @@ test('size report covers HTML, top-level and API directories', async () => { test('size budget defaults to warning and can be switched to a hard failure', () => { expect(readBudget({})).toEqual({ bytes: DEFAULT_DIST_SIZE_BUDGET_BYTES, mode: 'warn' }); expect(readBudget({ DIST_SIZE_BUDGET_BYTES: '', DIST_SIZE_BUDGET_MODE: '' }).mode).toBe('warn'); - expect(() => readBudget({ DIST_SIZE_BUDGET_BYTES: '10GB' })).toThrow(/positive integer/); - expect(() => readBudget({ DIST_SIZE_BUDGET_MODE: 'fail' })).toThrow(/'warn' or 'error'/); + const warnings: string[] = []; + const collect = (message: string) => warnings.push(message); + expect(readBudget({ DIST_SIZE_BUDGET_BYTES: '10GB' }, collect)).toEqual({ bytes: DEFAULT_DIST_SIZE_BUDGET_BYTES, mode: 'warn' }); + expect(readBudget({ DIST_SIZE_BUDGET_MODE: 'fail' }, collect).mode).toBe('warn'); + expect(warnings).toEqual([expect.stringMatching(/positive integer/), expect.stringMatching(/'warn' or 'error'/)]); expect(checkBudget(100, { bytes: 100, mode: 'warn' })).toMatchObject({ exceeded: false, fail: false, annotation: undefined }); const warn = checkBudget(101, { bytes: 100, mode: 'warn' });