Skip to content

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

TypeScript

ci: the PR report shows API changes after package size, one line with the rows collapsed (#9224)

Cindy Zhang2fa4cef5891d
diff --git a/.github/scripts/generate-pr-comment.js b/.github/scripts/generate-pr-comment.js
index 6764ab8b3c..a514964138 100644
--- a/.github/scripts/generate-pr-comment.js
+++ b/.github/scripts/generate-pr-comment.js
@@ -3,7 +3,7 @@
/**
* @description Generates the PR comment from the run's analysis results
- * @input --analysis <file> --base-stats <file> --package-size <file> --a11y <file> --visual <file> --visual-frames <file> --preview <file> --jobs <file> --touched <file> --source-conclusion <conclusion> --run-url <url>
+ * @input --analysis <file> --base-stats <file> --package-size <file> --api-changes <file> --a11y <file> --visual <file> --visual-frames <file> --preview <file> --jobs <file> --touched <file> --source-conclusion <conclusion> --run-url <url>
* @output Formatted markdown comment body to stdout, compact by design: this
* head's preview first, the modified components (preview links, size, lines
* of code, a mark per browser suite that ran; three rows visible, the rest
@@ -69,6 +69,8 @@ const touched = readOptionalJson('touched');
const packageSize = readOptionalJson('package-size');
// The visual frames publish-frames.mjs put on this PR's assets branch.
const visualFrames = readOptionalJson('visual-frames');
+// The API report step's changes for this head, when it ran.
+const apiChanges = readOptionalJson('api-changes');
const visualVerdict = readOptionalJson('visual');
let a11yReport = null;
try {
@@ -130,6 +132,7 @@ const report = buildCompactReport({
visualVerdict,
packageSize,
visualFrames,
+ apiChanges,
});
const footerLinksStr = runUrl
? ` | ${extLink('View full report', runUrl)}`
diff --git a/.github/scripts/lib/pr-preview.mjs b/.github/scripts/lib/pr-preview.mjs
index 79a878c431..6a2ff7181e 100644
--- a/.github/scripts/lib/pr-preview.mjs
+++ b/.github/scripts/lib/pr-preview.mjs
@@ -613,6 +613,7 @@ export async function reconcilePrComment({
metadataPath = 'pr-analysis/pr-meta.json',
baseStatsPath = 'pr-size-base/size-base.json',
packageSizePath = 'pr-analysis/package-size.json',
+ apiChangesPath = 'pr-analysis/api-changes.json',
visualFrames = null,
a11yPath = 'a11y/a11y-report.json',
visualPath = 'trusted-visual/verdict.json',
@@ -705,6 +706,10 @@ export async function reconcilePrComment({
})
? ['--package-size', packageSizePath]
: []),
+ // Part of the analysis artifact, which pr-meta.json ties to this head.
+ ...(fs.existsSync(apiChangesPath)
+ ? ['--api-changes', apiChangesPath]
+ : []),
// 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 eb9c69bfd9..510e5d918e 100644
--- a/.github/scripts/lib/pr-preview.test.mjs
+++ b/.github/scripts/lib/pr-preview.test.mjs
@@ -204,6 +204,7 @@ async function reconcile({
baseStats,
packageSize,
touched,
+ apiChanges,
} = {}) {
const value = previewAvailable
? {...requested, headRepository: requested.baseRepository}
@@ -221,6 +222,11 @@ async function reconcile({
);
if (packageSize)
fs.writeFileSync(packageSizePath, JSON.stringify(packageSize));
+ const apiChangesPath = path.join(
+ path.dirname(paths.analysis),
+ 'api-changes.json',
+ );
+ if (apiChanges) fs.writeFileSync(apiChangesPath, JSON.stringify(apiChanges));
const touchedPath = path.join(
path.dirname(paths.analysis),
'touched-components.json',
@@ -243,6 +249,7 @@ async function reconcile({
metadataPath: paths.metadata,
baseStatsPath,
packageSizePath,
+ apiChangesPath,
touchedPath,
a11yPath: paths.a11y,
visualPath: paths.visual,
@@ -1151,6 +1158,24 @@ describe('PR comment preview reconciliation', () => {
},
);
+ it.each([
+ ['written', true],
+ ['absent', false],
+ ])(
+ 'passes the API changes from the analysis artifact when %s',
+ async (_label, written) => {
+ const seen = [];
+ await reconcile({
+ apiChanges: written ? {version: 1, packages: []} : undefined,
+ execute: (_node, args) => {
+ seen.push(args);
+ return '## PR Analysis Report\n';
+ },
+ });
+ expect(seen[0].includes('--api-changes')).toBe(written);
+ },
+ );
+
it('falls back to a safe current message when analysis rendering fails', async () => {
const stale = {
id: 78,
diff --git a/.github/scripts/lib/pr-status.js b/.github/scripts/lib/pr-status.js
index be63034bba..26cc559ccc 100644
--- a/.github/scripts/lib/pr-status.js
+++ b/.github/scripts/lib/pr-status.js
@@ -10,8 +10,8 @@
* of modified components (preview links, JS and CSS size and lines of code
* against main, and a fixed-position mark per browser suite when any ran),
* three rows visible and the rest collapsed; the changed shots, collapsed,
- * when any changed; one line for package size; one line for suites that
- * did not run
+ * when any changed; one line for package size; one line for API changes,
+ * with their rows collapsed; one line for suites that did not run
* @position Used by generate-pr-comment.js. Everything here reads data the CI
* run and the comment job already have; nothing starts a job. GitHub shows
* the CI checks and CodeBunny posts its own review, so neither is repeated.
@@ -515,6 +515,21 @@ function notRunLine({jobs, a11yReport, visualVerdict, touched = null}) {
return `Not run on this PR: add ${list} to run ${labels.length === 1 ? 'it' : 'them'}.\n\n`;
}
+// The API report step's own renderer (scripts/api-report/changes.mjs), so
+// the PR report and `pnpm api:report` show API changes one way.
+const {renderChanges} = require('../../../scripts/api-report/changes.mjs');
+
+/**
+ * API changes (the API report step's api-changes.json): one visible line per
+ * package, the rows in one closed disclosure; nothing when no package has a
+ * change or a report to refresh.
+ */
+function apiChangesLine(report) {
+ if (!report || !Array.isArray(report.packages)) return '';
+ const out = renderChanges(report.packages);
+ return out ? `${out}\n` : '';
+}
+
/** The compact report body, between the heading and the footer. */
function buildCompactReport({
analysis,
@@ -524,6 +539,7 @@ function buildCompactReport({
a11yReport = null,
visualVerdict = null,
packageSize = null,
+ apiChanges = null,
visualFrames = null,
}) {
const origin =
@@ -534,10 +550,11 @@ function buildCompactReport({
touched,
a11yReport,
visualVerdict,
- })}${buildVisualDeltas({verdict: visualVerdict, frames: visualFrames})}${packagesLine(packageSize)}${notRunLine({jobs, a11yReport, visualVerdict, touched})}`;
+ })}${buildVisualDeltas({verdict: visualVerdict, frames: visualFrames})}${packagesLine(packageSize)}${apiChangesLine(apiChanges)}${notRunLine({jobs, a11yReport, visualVerdict, touched})}`;
}
module.exports = {
+ apiChangesLine,
visualShots,
SUITES,
VISUAL_FRAME_LIMIT,
diff --git a/.github/scripts/lib/pr-status.test.mjs b/.github/scripts/lib/pr-status.test.mjs
index 75009bca86..a53e0de2c2 100644
--- a/.github/scripts/lib/pr-status.test.mjs
+++ b/.github/scripts/lib/pr-status.test.mjs
@@ -24,6 +24,7 @@ const {
buildVisualDeltas,
previewLine,
packagesLine,
+ apiChangesLine,
notRunLine,
SUITES,
VISUAL_FRAME_LIMIT,
@@ -451,6 +452,113 @@ describe('packagesLine', () => {
});
});
+describe('apiChangesLine', () => {
+ const pkg = (name, rows, extra = {}) => ({
+ pkg: `@astryxdesign/${name}`,
+ baseline: false,
+ stale: false,
+ missing: false,
+ counts: {
+ added: rows.filter(row => row.change === 'added').length,
+ changed: rows.filter(row => row.change === 'changed').length,
+ removed: rows.filter(row => row.change === 'removed').length,
+ },
+ rows,
+ ...extra,
+ });
+ const row = (change, item, extra = {}) => ({
+ change,
+ entry: '.',
+ section: 'Components',
+ item,
+ member: null,
+ line: `${item} line`,
+ usage: `<${item.split(' ').at(-1)} />`,
+ ...extra,
+ });
+
+ it("renders with the API report step's own renderer: counts on one line, rows with usage in a closed disclosure", () => {
+ const out = apiChangesLine({
+ version: 1,
+ packages: [
+ pkg(
+ 'core',
+ [
+ row('added', 'component AppShell'),
+ row('changed', 'component Button', {
+ before: "size = 'md'",
+ line: "size = 'sm'",
+ }),
+ row('removed', 'hook useToast'),
+ ],
+ {stale: true},
+ ),
+ pkg('lab', []),
+ pkg('richtext', [], {missing: true}),
+ pkg('charts', [], {baseline: true}),
+ ],
+ });
+ expect(out.split('\n')[0]).toBe(
+ '**API changes:** `core` +1 · ~1 · −1 (report stale: run `pnpm api:report`); `richtext` no changes (report not committed: run `pnpm api:report`); `charts` new report',
+ );
+ expect(out).toContain(
+ '<details><summary>3 API changes (advisory)</summary>',
+ );
+ expect(out).toContain('| Package | Where | Signature | Usage |');
+ expect(out).toContain(
+ "| ~ | `core` | `. · Components · component Button` | `size = 'md'` → `size = 'sm'` | `<Button />` |",
+ );
+ expect(out).not.toContain('`lab`');
+ expect(out.endsWith('</details>\n\n')).toBe(true);
+ });
+
+ it('renders every string from the file as a code span: no HTML, markup or link', () => {
+ const out = apiChangesLine({
+ packages: [
+ pkg('www.evil.example', [
+ row('added', '<img src=x onerror=alert(1)>', {
+ line: 'a | b [link](https://evil.example) `tick`',
+ usage: 'https://evil.example',
+ // A row's own `pkg` never replaces the code-spanned name.
+ pkg: '[evil](https://evil.example)',
+ }),
+ ]),
+ ],
+ });
+ expect(out).toContain('**API changes:** `www.evil.example` +1');
+ expect(out).toContain('`` a \\| b [link](https://evil.example) `tick` ``');
+ expect(out).toContain('`https://evil.example` |');
+ // Outside code spans, no URL, tag or link syntax remains.
+ const outside = out.replace(/(`+)[\s\S]*?\1/g, '');
+ expect(outside).not.toMatch(/https?:|www\.|<img|\]\(/);
+ });
+
+ it('prompts for a report that neither the merge base nor the head commits', () => {
+ expect(
+ apiChangesLine({
+ version: 1,
+ packages: [pkg('core', [], {baseline: true, missing: true})],
+ }),
+ ).toBe(
+ '**API changes:** `core` no changes (report not committed: run `pnpm api:report`)\n\n',
+ );
+ });
+
+ it('lists at most 150 rows and counts the rest', () => {
+ const rows = Array.from({length: 160}, (_, i) => row('added', `item ${i}`));
+ const out = apiChangesLine({packages: [pkg('core', rows)]});
+ expect(out.match(/^\| \+ \| `core` \|/gm)).toHaveLength(150);
+ expect(out).toContain('…and 10 more;');
+ });
+
+ it('is absent when no package has a change or a report to refresh, or without a file', () => {
+ expect(
+ apiChangesLine({version: 1, packages: [pkg('core', []), pkg('lab', [])]}),
+ ).toBe('');
+ expect(apiChangesLine(null)).toBe('');
+ });
+});
+
describe('notRunLine', () => {
const skipped = name => ({name, conclusion: 'skipped', steps: []});
diff --git a/scripts/api-report/api-report.test.mjs b/scripts/api-report/api-report.test.mjs
index 6d0dc7ce10..f81365e780 100644
--- a/scripts/api-report/api-report.test.mjs
+++ b/scripts/api-report/api-report.test.mjs
@@ -171,7 +171,7 @@ describe('API changes', () => {
]),
);
expect(md.split('\n')[0]).toBe(
- '**API changes:** demo +0 · ~1 · −0 (report stale: run `pnpm api:report`)',
+ '**API changes:** `demo` +0 · ~1 · −0 (report stale: run `pnpm api:report`)',
);
expect(md).toContain('<details><summary>1 API change (advisory)</summary>');
expect(md).toContain('`<Chip size="sm" />`');
@@ -186,7 +186,9 @@ describe('API changes', () => {
rows: [],
counts: {added: 0, changed: 0, removed: 0},
});
- expect(renderChanges([change])).toBe('**API changes:** demo new report\n');
+ expect(renderChanges([change])).toBe(
+ '**API changes:** `demo` new report\n',
+ );
});
it('gives package-level rows a usage example of their own kind', () => {
diff --git a/scripts/api-report/changes.mjs b/scripts/api-report/changes.mjs
index 948410d01a..779514044e 100644
--- a/scripts/api-report/changes.mjs
+++ b/scripts/api-report/changes.mjs
@@ -214,9 +214,30 @@ export function computeChanges(packages) {
// The pull request comment has a size limit; a wide change lists its first rows.
const MAX_ROWS = 150;
-const code = s => `\`${s.replace(/`/g, "'").replace(/\|/g, '\\|')}\``;
-const where = r => [r.entry, r.section, r.item].filter(Boolean).join(' · ');
-const short = pkg => pkg.replace(/^@astryxdesign\//, '');
+/**
+ * Literal text as a code span, for every string the report renders: no link
+ * (GitHub autolinks a bare URL in plain text), no markup, no HTML. The pull
+ * request's own build writes these strings and the comment is public. A pipe
+ * is escaped so a table cell stays one cell; the fence is longer than any
+ * backtick run inside.
+ */
+const code = value => {
+ const text = String(value ?? '')
+ .replace(/\s*[\r\n]+\s*/g, ' ')
+ .replace(/\|/g, '\\|');
+ if (text.trim() === '') return '';
+ const longest = Math.max(
+ 0,
+ ...(text.match(/`+/g) || []).map(run => run.length),
+ );
+ const fence = '`'.repeat(longest + 1);
+ const pad = text.startsWith('`') || text.endsWith('`') ? ' ' : '';
+ return `${fence}${pad}${text}${pad}${fence}`;
+};
+const count = value => (Number.isFinite(Number(value)) ? Number(value) : 0);
+const where = r =>
+ code([r.entry, r.section, r.item].filter(Boolean).join(' · '));
+const short = pkg => code(String(pkg ?? '').replace(/^@astryxdesign\//, ''));
/**
* The advisory API changes for the pull request report: one visible summary
@@ -225,25 +246,32 @@ const short = pkg => pkg.replace(/^@astryxdesign\//, '');
* @returns {string} empty when nothing changed and every report is current
*/
export function renderChanges(changes) {
- const touched = changes.filter(
- c => c.rows.length || c.stale || c.missing || c.baseline,
- );
+ const touched = (Array.isArray(changes) ? changes : [])
+ .map(c => ({...c, rows: Array.isArray(c?.rows) ? c.rows : []}))
+ .filter(
+ c =>
+ c.rows.length ||
+ c.stale === true ||
+ c.missing === true ||
+ c.baseline === true,
+ );
if (!touched.length) return '';
const parts = touched.map(c => {
- if (c.baseline && !c.missing)
+ if (c.baseline === true && c.missing !== true)
return `${short(c.pkg)} new report${c.stale ? ' (stale: run `pnpm api:report`)' : ''}`;
const counts = c.rows.length
- ? ` +${c.counts.added} · ~${c.counts.changed} · −${c.counts.removed}`
+ ? ` +${count(c.counts?.added)} · ~${count(c.counts?.changed)} · −${count(c.counts?.removed)}`
: ' no changes';
- const note = c.missing
- ? ' (report not committed: run `pnpm api:report`)'
- : c.stale
- ? ' (report stale: run `pnpm api:report`)'
- : '';
+ const note =
+ c.missing === true
+ ? ' (report not committed: run `pnpm api:report`)'
+ : c.stale === true
+ ? ' (report stale: run `pnpm api:report`)'
+ : '';
return `${short(c.pkg)}${counts}${note}`;
});
const rows = touched.flatMap(c =>
- c.rows.map(r => ({pkg: short(c.pkg), ...r})),
+ c.rows.map(r => ({...r, pkg: short(c.pkg)})),
);
const L = [`**API changes:** ${parts.join('; ')}`];
if (rows.length) {
@@ -257,7 +285,7 @@ export function renderChanges(changes) {
const sign =
r.change === 'added' ? '+' : r.change === 'removed' ? '−' : '~';
const sig =
- r.change === 'changed'
+ r.change === 'changed' && r.before != null
? `${code(r.before)} → ${code(r.line)}`
: code(r.line);
return `| ${sign} | ${r.pkg} | ${where(r)} | ${sig} | ${code(r.usage)} |`;