Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion .github/workflows/frontend-build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
206 changes: 158 additions & 48 deletions src/frontend/scripts/measure-build-output.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -7,42 +7,146 @@ 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<string, { path: string, files: number, bytes: number, htmlFiles: number, markdownFiles: number }>} */
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;
if (file.path.endsWith('.html')) group.htmlFiles++;
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, 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();
let bytes = raw ? Number(raw) : DEFAULT_DIST_SIZE_BUDGET_BYTES;
if (!Number.isSafeInteger(bytes) || bytes <= 0) {
warn(`DIST_SIZE_BUDGET_BYTES must be a positive integer, got '${raw}'; using ${DEFAULT_DIST_SIZE_BUDGET_BYTES}.`);
bytes = DEFAULT_DIST_SIZE_BUDGET_BYTES;
}
let mode = (env.DIST_SIZE_BUDGET_MODE?.trim() || 'warn').toLowerCase();
if (mode !== 'warn' && mode !== 'error') {
warn(`DIST_SIZE_BUDGET_MODE must be 'warn' or 'error', got '${mode}'; using 'warn'.`);
mode = 'warn';
}
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)} |`,
'',
'<details><summary>Top-level directories (locale folders included)</summary>',
'',
...header,
...output.topLevel.map(row),
'',
'</details>',
'',
...(apiGroups.length ? [
'<details><summary><code>reference/api</code> by language</summary>',
'',
...header,
...apiGroups.map(row),
'',
'</details>',
'',
] : []),
].join('\n');
}

export async function sampleCompression(directory, files) {
// Stratify by output directory; cap this diagnostic so profiling doesn't re-compress dist.
const selected = [];
Expand Down Expand Up @@ -72,43 +176,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();
}
}
60 changes: 58 additions & 2 deletions src/frontend/tests/unit/build-performance.vitest.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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[] = [];
Expand Down Expand Up @@ -107,10 +114,59 @@ 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');
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' });
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];
Expand Down
Loading