Skip to content

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

TypeScript

ci(api-report): compare a pull request's API changes with its merge base's built surface (#9348)

Cindy Zhanga46b203df23a
diff --git a/.github/scripts/ci-tooling-routing.test.mjs b/.github/scripts/ci-tooling-routing.test.mjs
index e4f1b49e40..c6ea276028 100644
--- a/.github/scripts/ci-tooling-routing.test.mjs
+++ b/.github/scripts/ci-tooling-routing.test.mjs
@@ -347,6 +347,163 @@ describe('Node-tooling CI routing', () => {
}
});
+ it("compares the merge base's API surface from main's kept record, or from a base built for its sizes", () => {
+ const main = load('.github/workflows/deploy.yml');
+ const record = step(
+ main.jobs.typecheck,
+ 'Record the published API surface',
+ );
+ expect(record.run).toBe(
+ 'node scripts/api-report/cli.mjs --surface api-surface',
+ );
+ // Evidence only (INV24): neither step can fail main's validation.
+ expect(record['continue-on-error']).toBe(true);
+ const keep = step(
+ main.jobs.typecheck,
+ "Keep this commit's API surface for PR API changes",
+ );
+ expect(keep['continue-on-error']).toBe(true);
+ expect(keep.with).toMatchObject({
+ name: 'api-surface-main-${{ needs.main-commit.outputs.sha }}',
+ path: 'api-surface/',
+ 'retention-days': 14,
+ });
+ const mainNames = main.jobs.typecheck.steps.map(entry => entry.name);
+ expect(
+ mainNames.indexOf('Record the published API surface'),
+ ).toBeGreaterThan(
+ main.jobs.typecheck.steps.findIndex(entry => entry.run === 'pnpm build'),
+ );
+
+ const job = ci.jobs['build-storybook'];
+ const find = step(job, "Find main's size records for the merge base");
+ expect(find.with.script).toContain("['api_run_id', 'api-surface-main'");
+ const download = step(
+ job,
+ "Download main's API surface for the merge base",
+ );
+ expect(download.id).toBe('api-download');
+ expect(download['continue-on-error']).toBe(true);
+ expect(download.with).toMatchObject({
+ name: 'api-surface-main-${{ steps.merge-base.outputs.sha }}',
+ 'run-id': '${{ steps.size-records.outputs.api_run_id }}',
+ path: '.api-surface-base',
+ });
+ const start = step(job, 'Start building the merge base without a record');
+ // A missing API surface alone starts no build (the API report's budget):
+ // the base builds only for a missing size record, and then also writes
+ // its API surface when Main kept none and the head can.
+ expect(start.if).not.toContain('api-download');
+ // The head's API report script runs only in the step guarded for it.
+ expect(start.run).not.toContain('scripts/api-report/cli.mjs');
+ expect(start.env.NEED_API).toBe(
+ "${{ steps.api-download.outcome != 'success' }}",
+ );
+ expect(start.run).toContain('pnpm -F @astryxdesign/cli sync:api-types');
+ const names = job.steps.map(entry => entry.name);
+ const at = name => names.indexOf(name);
+ expect(at("Download main's API surface for the merge base")).toBeLessThan(
+ at('Start building the merge base without a record'),
+ );
+ expect(at("Wait for the merge base's sizes")).toBeLessThan(
+ at('Report API changes'),
+ );
+ expect(step(job, 'Report API changes')['continue-on-error']).toBe(true);
+ });
+
+ // The stub CLI writes a surface when asked for one (or fails to, for a
+ // base whose surface cannot be written) and prints the --changes call.
+ const stubCli = ({supported, surfaceWrites = true}) =>
+ `${supported ? "// '--base-surface'\n" : ''}import fs from 'node:fs';
+const args = process.argv.slice(2);
+if (args[0] === '--surface') {
+ if (!${surfaceWrites}) process.exit(1);
+ fs.mkdirSync(args[1], {recursive: true});
+ fs.writeFileSync(args[1] + '/surface.json', JSON.stringify(args));
+} else console.log(JSON.stringify(args));
+`;
+
+ it.each([
+ [
+ 'main kept',
+ {main: true},
+ ['--base-surface', '.api-surface-base', '--base-record', 'main'],
+ ],
+ [
+ 'of the base this run built for its sizes',
+ {built: true},
+ ['--base-surface', '.api-surface-build', '--base-record', 'build'],
+ ],
+ ['nobody kept or built', {}, []],
+ [
+ 'of a built base whose surface cannot be written',
+ {built: true, surfaceWrites: false},
+ [],
+ ],
+ ['main kept, for a head predating it,', {main: true, supported: false}, []],
+ ])(
+ 'compares the API changes with the surface %s',
+ (
+ _label,
+ {main = false, built = false, supported = true, surfaceWrites = true},
+ extra,
+ ) => {
+ const report = step(ci.jobs['build-storybook'], 'Report API changes');
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'api-changes-'));
+ try {
+ fs.mkdirSync(path.join(root, 'scripts/api-report'), {recursive: true});
+ fs.mkdirSync(path.join(root, '.github/scripts'), {recursive: true});
+ fs.writeFileSync(
+ path.join(root, '.github/scripts/merge-base.sh'),
+ 'echo abc123\n',
+ );
+ fs.chmodSync(path.join(root, '.github/scripts/merge-base.sh'), 0o755);
+ fs.writeFileSync(
+ path.join(root, 'scripts/api-report/cli.mjs'),
+ stubCli({supported, surfaceWrites}),
+ );
+ if (main) {
+ fs.mkdirSync(path.join(root, '.api-surface-base'));
+ fs.writeFileSync(
+ path.join(root, '.api-surface-base/surface.json'),
+ '{}',
+ );
+ }
+ if (built) {
+ fs.mkdirSync(path.join(root, '.size-base'));
+ fs.writeFileSync(path.join(root, 'base-build.done'), '');
+ }
+ const out = execFileSync('bash', ['-e', '-c', report.run], {
+ cwd: root,
+ encoding: 'utf8',
+ env: {...process.env, BASE_REF: 'main'},
+ });
+ expect(JSON.parse(out.trim().split('\n').at(-1))).toEqual([
+ '--changes',
+ '--base',
+ 'abc123',
+ ...extra,
+ ]);
+ if (built && surfaceWrites && supported)
+ expect(
+ JSON.parse(
+ fs.readFileSync(
+ path.join(root, '.api-surface-build/surface.json'),
+ 'utf8',
+ ),
+ ),
+ ).toEqual([
+ '--surface',
+ '.api-surface-build',
+ '--root',
+ '.size-base',
+ ]);
+ } finally {
+ fs.rmSync(root, {recursive: true, force: true});
+ }
+ },
+ );
+
it('builds no Sandbox and builds Storybook once per pull-request run', () => {
// Vercel builds the Sandbox preview; nothing downloaded CI's copy.
expect(ci.jobs['build-sandbox']).toBeUndefined();
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ca2ca7bbc5..6e620d7336 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1050,11 +1050,12 @@ jobs:
if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
uses: ./.github/actions/setup
- # Main keeps each commit's size records for 14 days (deploy.yml): every
- # public component's sizes and every published package's. The merge
- # base is compared from them; it is built here only when Main kept no
- # component record for it. The lookup runs before the Storybook build so
- # that build can run beside it.
+ # Main keeps each commit's size records and API surface for 14 days
+ # (deploy.yml): every public component's sizes, every published
+ # package's, and every published package's API report. The merge base is
+ # compared from them; it is built here only when Main kept no component
+ # record for it. The lookup runs before the Storybook build so that build
+ # can run beside it.
- name: Find the merge base
id: merge-base
if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request'
@@ -1076,6 +1077,7 @@ jobs:
for (const [output, prefix, missing] of [
['component_run_id', 'component-size-main', 'the merge base is built here instead'],
['package_run_id', 'package-size-main', 'package sizes are shown without a budget'],
+ ['api_run_id', 'api-surface-main', 'the API changes compare with its committed reports unless the merge base is built for its sizes'],
]) {
const name = `${prefix}-${process.env.BASE_SHA}`;
const runId = await mainArtifactRunId({github, ...context.repo, name, sha: process.env.BASE_SHA});
@@ -1094,21 +1096,38 @@ jobs:
github-token: ${{ github.token }}
path: .component-size-base
+ - name: Download main's API surface for the merge base
+ id: api-download
+ if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.size-records.outputs.api_run_id != ''
+ continue-on-error: true
+ uses: actions/download-artifact@v8
+ with:
+ name: api-surface-main-${{ steps.merge-base.outputs.sha }}
+ run-id: ${{ steps.size-records.outputs.api_run_id }}
+ github-token: ${{ github.token }}
+ path: .api-surface-base
+
# No component record of this merge base was read (Main kept none, or
- # its download failed): build the base beside
- # the Storybook build and record its sizes with this head's analyzer, so
- # every changed component still has a before size (AST-080 FR8). It runs
- # in the background; the wait before the analysis collects it.
+ # its download failed): build the base beside the Storybook build and
+ # record its sizes with this head's analyzer, so every changed component
+ # still has a before size (AST-080 FR8). When Main kept no API surface
+ # either, it also builds the published packages the pull request
+ # changes, and the API changes step reports this base (INV24). A missing
+ # API surface alone starts no build: the API changes then compare with
+ # the merge base's committed reports, marked as such. It runs in the
+ # background; the wait before the analysis collects it.
- name: Start building the merge base without a record
id: base-build
if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.merge-base.outputs.sha != '' && steps.component-download.outcome != 'success'
env:
BASE_SHA: ${{ steps.merge-base.outputs.sha }}
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+ NEED_API: ${{ steps.api-download.outcome != 'success' }}
run: |
git worktree add --detach .size-base "$BASE_SHA"
mkdir -p .component-size-base
- # The inner script reads BASE_SHA and HEAD_SHA from this step's env.
+ # The inner script reads BASE_SHA, HEAD_SHA and NEED_API from this
+ # step's env.
# shellcheck disable=SC2016
nohup bash -c '
set -e
@@ -1116,13 +1135,25 @@ jobs:
pnpm install --frozen-lockfile
# Core and its build tooling always build: the other component
# packages depend on them. Another package builds only when the
- # pull request changes its source.
+ # pull request changes its source. A published package the base
+ # leaves unbuilt is reported from the head build only when none of
+ # its report inputs changed (the API report CLI's SHARED_INPUTS);
+ # otherwise from its committed report.
pnpm -F @astryxdesign/build build
pnpm -F @astryxdesign/core build
for pkg in lab charts richtext vega; do
git diff --quiet "$BASE_SHA" "$HEAD_SHA" -- "packages/$pkg/src" || pnpm -F "@astryxdesign/$pkg" build
done
node ../.github/scripts/analyze-pr.js --main-record --output ../.component-size-base/component-size.json
+ if [ "$NEED_API" = true ]; then
+ {
+ for dir in packages/themes/*/; do
+ git diff --quiet "$BASE_SHA" "$HEAD_SHA" -- "$dir" || pnpm -F "./$dir" build
+ done
+ # The CLI publishes declarations generated from its JSDoc.
+ git diff --quiet "$BASE_SHA" "$HEAD_SHA" -- packages/cli || pnpm -F @astryxdesign/cli sync:api-types
+ } || echo "Building the merge base's published packages failed; those packages compare with its committed reports."
+ fi
touch ../base-build.done
' > base-build.log 2>&1 || touch base-build.failed &
echo "started=true" >> "$GITHUB_OUTPUT"
@@ -1308,8 +1339,10 @@ jobs:
EOF
# Advisory API changes (architecture:public-component-api INV24): each
- # published package's report from this build, compared with the reports
- # committed at the merge base (read with git, no API calls). It reads the
+ # published package's report from this build, compared with the merge
+ # base's surface (Main's record of it, else the base built above, else
+ # the reports committed there, read with git). A committed report that
+ # differs from this build is one stale line, not rows. It reads the
# dists built above and never fails the job; api-changes.json goes into
# the pr-analysis artifact. With no merge base there is nothing to compare.
# A head cut before cli.mjs existed cannot run the next step;
@@ -1327,7 +1360,22 @@ jobs:
run: |
BASE_SHA=$(.github/scripts/merge-base.sh "$BASE_REF" 'the API changes' || true)
[ -n "$BASE_SHA" ] || exit 0
- node scripts/api-report/cli.mjs --changes --base "$BASE_SHA"
+ # Main's surface of the merge base, else the base built above for its
+ # sizes, reported here. A head that predates the built surface
+ # compares committed reports.
+ SURFACE=()
+ if grep -q -- "'--base-surface'" scripts/api-report/cli.mjs; then
+ if [ -f .api-surface-base/surface.json ]; then
+ SURFACE=(--base-surface .api-surface-base --base-record main)
+ elif [ -f base-build.done ] && [ -d .size-base ]; then
+ node scripts/api-report/cli.mjs --surface .api-surface-build --root .size-base \
+ || echo "::notice::The merge base's API surface was not written; the API changes compare with its committed reports."
+ if [ -f .api-surface-build/surface.json ]; then
+ SURFACE=(--base-surface .api-surface-build --base-record build)
+ fi
+ fi
+ fi
+ node scripts/api-report/cli.mjs --changes --base "$BASE_SHA" "${SURFACE[@]}"
- name: Upload analysis artifact
if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && (github.event_name == 'pull_request' || inputs.operation == 'release-check')
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 7685341dd6..6957081c44 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -238,6 +238,24 @@ jobs:
path: package-size.json
retention-days: 14
+ # A pull request's API changes compare its head's build with this
+ # surface of its merge base (ci.yml build-storybook), so a committed
+ # report main forgot to regenerate never shows as a pull request's rows
+ # (architecture:public-component-api INV24). Evidence only: it never
+ # fails this job.
+ - name: Record the published API surface
+ continue-on-error: true
+ run: node scripts/api-report/cli.mjs --surface api-surface
+
+ - name: Keep this commit's API surface for PR API changes
+ if: hashFiles('api-surface/surface.json') != ''
+ continue-on-error: true
+ uses: actions/upload-artifact@v7
+ with:
+ name: api-surface-main-${{ needs.main-commit.outputs.sha }}
+ path: api-surface/
+ retention-days: 14
+
- name: Verify package exports
run: node scripts/verify-exports.mjs
diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md
index 016351cb03..8a272682bc 100644
--- a/docs/architecture/public-component-api.md
+++ b/docs/architecture/public-component-api.md
@@ -258,11 +258,11 @@ guidance owns the process used to propose and test APIs.
appears (INV12); Core's `./internal/*` subpaths and unpublished packages,
including Lab, do not. A member inside a canonical experimental boundary
appears marked experimental (`spec:AST-017` FR21). The pull-request report
- lists the API changes between the merge base's report and one generated from
- the head's build: added, changed, and removed rows, each with its signature
- and a usage example, and flags a committed report that differs from the head's
- build as stale. The report and its changes are evidence: they fail no check
- and decide no acceptance (INV13).
+ lists the API changes between the reports built from the merge base and from
+ the head: added, changed, and removed rows, each with its signature and a
+ usage example, and flags a committed report that differs from the head's
+ build as stale, in one line. The report and its changes are evidence: they
+ fail no check and decide no acceptance (INV13).
- **INV25 — Undeclared public API goes to a human.** Review compares each added
or changed row of a pull request's API changes with current records. A row
that a record current at the merge base, or a record change in the same pull
@@ -365,7 +365,7 @@ copy the component matrix.
| INV21 | Public-API review against existing props, components, hooks, and factories | A new API that shares a job with an existing one that is not being deprecated in its favor |
| INV22 | Public-API review of each public gesture, press, drag, or motion hook against its `create…` factory | A public interaction hook with no public factory taking the same options and returning `destroy()`, outside the listed exemptions |
| INV23 | `@astryx/no-raw-private-attribute` lint with its baseline (test files exempt), plus public-API review of the public list | A `data-astryx-*` name or selector written outside its owner module, a test, or the public list; a `dataAttr()` call that names a private attribute; an owner module that exports its raw name or a selector; a package that imports another package's owner module; a caller that sets a property an owner style it spreads also sets; a private attribute in a public export, `.doc.mjs`, or Changeset; a baseline entry added; a public data attribute changed without INV9 evidence |
-| INV24 | API report generator tests over representative entry points, plus the pull-request report's API changes | A promised export, prop, hook, type, custom property, theme target, or public attribute is missing from a report; a reachable internal-tagged member is missing; an `./internal/*` or Lab member appears; a stale committed report is not flagged; the check fails a pull request |
+| INV24 | API report generator tests over representative entry points, plus the pull-request report's API changes | A promised export, prop, hook, type, custom property, theme target, or public attribute is missing from a report; a reachable internal-tagged member is missing; an `./internal/*` or Lab member appears; a stale committed report is not flagged, or its rows are listed as the pull request's API changes; the check fails a pull request |
| INV25 | Public-API review routing against the pull request's API changes | A row that no current record decides does not reach human review; a row a current record decides is held for a human; an undeclared row alone draws a request for changes |
| Consumer-doc projection | `docPropReferences.test.ts` and `docPropLiterals.test.ts` | Docs name a nonexistent prop or omit public literal choices |
@@ -382,11 +382,12 @@ Known verification gaps:
- The passthrough lint is warning-only while known violations remain.
- The current source-to-doc completeness matcher still looks for old prefixed
props interfaces, so it does not yet prove full prop coverage.
-- INV24: `pnpm api:report` and the committed reports do not exist yet, so
- reviews build the reachable public inventory explicitly. The reports cover
- declarations, CSS custom properties, theme targets, and public attributes;
- context-member behavior, undeclared defaults, CLI schemas, and observable
- behavior for both the branch and synthetic merge still need explicit review.
+- INV24: the reports cover declarations, CSS custom properties, theme targets,
+ and public attributes; context-member behavior, undeclared defaults, CLI
+ schemas, and observable behavior for both the branch and synthetic merge
+ still need explicit review. When no build of the merge base is kept, the
+ API changes compare with the merge base's committed reports, marked as
+ such, and list the rows a stale committed report carries.
- INV18: shipped content slots that their anatomy does not name yet include
PowerSearch's `startIcon` and `endContent`, SideNav's `topContent`,
`footer`, and `footerIcons`, Tokenizer's `startIcon`, DropdownMenu's
diff --git a/scripts/api-report/api-report.test.mjs b/scripts/api-report/api-report.test.mjs
index f81365e780..74fbbe4afc 100644
--- a/scripts/api-report/api-report.test.mjs
+++ b/scripts/api-report/api-report.test.mjs
@@ -9,6 +9,9 @@
* @position scripts/api-report — guards architecture:public-component-api INV24
*/
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {beforeAll, describe, expect, it} from 'vitest';
@@ -19,7 +22,7 @@ import {
renderChanges,
usageFor,
} from './changes.mjs';
-import {publishedPackages} from './cli.mjs';
+import {chooseBase, publishedPackages} from './cli.mjs';
import {generateReport} from './generate.mjs';
const FIXTURE_ROOT = path.join(
@@ -159,7 +162,7 @@ describe('API changes', () => {
]);
});
- it('renders one summary line, keeps the rows in a closed disclosure, and flags a stale report', () => {
+ it('renders one summary line, keeps the rows in a closed disclosure, and flags a stale report in one line', () => {
const md = renderChanges(
computeChanges([
{
@@ -167,16 +170,108 @@ describe('API changes', () => {
base: report,
head: resize(report),
committed: report,
+ baseSource: 'build',
},
]),
);
- expect(md.split('\n')[0]).toBe(
- '**API changes:** `demo` +0 · ~1 · −0 (report stale: run `pnpm api:report`)',
- );
+ expect(md.split('\n').slice(0, 3)).toEqual([
+ '**API changes:** `demo` +0 · ~1 · −0',
+ '',
+ 'Committed API report behind this build: `demo` 1 row; run `pnpm api:report`.',
+ ]);
expect(md).toContain('<details><summary>1 API change (advisory)</summary>');
expect(md).toContain('`<Chip size="sm" />`');
});
+ // Main changed the API without regenerating its report; this pull request
+ // adds one type. Only the type is this pull request's.
+ const addTone = text =>
+ text.replace(
+ '### Types\n\n```text\n',
+ "### Types\n\n```text\ntype ChipTone = 'neutral' | 'accent'\n",
+ );
+
+ it("lists only the pull request's rows when the committed report is behind main", () => {
+ const [change] = computeChanges([
+ {
+ pkg: '@astryxdesign/demo',
+ base: resize(report),
+ head: addTone(resize(report)),
+ committed: report,
+ baseSource: 'build',
+ },
+ ]);
+ expect(change.rows.map(r => r.line)).toEqual([
+ "type ChipTone = 'neutral' | 'accent'",
+ ]);
+ expect(change).toMatchObject({stale: true, staleRows: 2});
+ const md = renderChanges([change]);
+ expect(md).toContain('**API changes:** `demo` +1 · ~0 · −0\n');
+ expect(md).toContain(
+ 'Committed API report behind this build: `demo` 2 rows; run `pnpm api:report`.',
+ );
+ expect(md).toContain('<details><summary>1 API change (advisory)</summary>');
+ expect(md).not.toContain("prop size?: ChipSize = 'sm'");
+ });
+
+ it('renders a stale report with no API change as one line', () => {
+ const md = renderChanges(
+ computeChanges([
+ {
+ pkg: '@astryxdesign/demo',
+ base: resize(report),
+ head: resize(report),
+ committed: report,
+ baseSource: 'build',
+ },
+ {
+ pkg: '@astryxdesign/other',
+ base: report,
+ head: report,
+ committed: report,
+ baseSource: 'build',
+ },
+ ]),
+ );
+ expect(md).toBe(
+ '**API changes:** none in this pull request\n\nCommitted API report behind this build: `demo` 1 row; run `pnpm api:report`.\n',
+ );
+ });
+
+ it("says when rows were compared with the merge base's committed report", () => {
+ const md = renderChanges(
+ computeChanges([
+ {
+ pkg: '@astryxdesign/demo',
+ base: report,
+ head: resize(report),
+ committed: resize(report),
+ baseSource: 'committed',
+ },
+ ]),
+ );
+ expect(md.split('\n')[0]).toBe(
+ "**API changes:** `demo` +0 · ~1 · −0 (against the merge base's committed report)",
+ );
+ expect(md).not.toContain('Committed API report behind');
+ });
+
+ it('renders version 1 changes as before', () => {
+ const md = renderChanges([
+ {
+ pkg: '@astryxdesign/demo',
+ baseline: false,
+ stale: true,
+ missing: false,
+ counts: {added: 0, changed: 0, removed: 0},
+ rows: [],
+ },
+ ]);
+ expect(md).toBe(
+ '**API changes:** `demo` no changes (report stale: run `pnpm api:report`)\n',
+ );
+ });
+
it('summarizes a package with no report at the merge base as a new report', () => {
const [change] = computeChanges([
{pkg: '@astryxdesign/demo', base: null, head: report, committed: report},
@@ -191,6 +286,33 @@ describe('API changes', () => {
);
});
+ it.each([
+ [
+ 'its built surface',
+ {surface: 'S', haveSurface: true, unchanged: false},
+ {base: 'S', baseSource: 'build'},
+ ],
+ [
+ 'this build for a package the built merge base lacks and this pull request leaves unchanged',
+ {surface: null, haveSurface: true, unchanged: true},
+ {base: 'H', baseSource: 'head'},
+ ],
+ [
+ 'the committed report for a changed package the built merge base lacks',
+ {surface: null, haveSurface: true, unchanged: false},
+ {base: 'C', baseSource: 'committed'},
+ ],
+ [
+ 'the committed report when no build of the merge base was kept',
+ {surface: null, haveSurface: false, unchanged: true},
+ {base: 'C', baseSource: 'committed'},
+ ],
+ ])("takes the merge base's report from %s", (_label, input, expected) => {
+ expect(chooseBase({...input, head: 'H', committedAtBase: 'C'})).toEqual(
+ expected,
+ );
+ });
+
it('gives package-level rows a usage example of their own kind', () => {
const rows = [...parseReport(report).values()];
const usage = item =>
@@ -225,3 +347,67 @@ describe('API changes', () => {
expect(renderChanges(changes)).toBe('');
});
});
+
+describe('--surface', () => {
+ const surface = (repoRoot, out) => {
+ execFileSync(
+ process.execPath,
+ [
+ path.join(path.dirname(fileURLToPath(import.meta.url)), 'cli.mjs'),
+ '--surface',
+ out,
+ '--root',
+ repoRoot,
+ ],
+ {encoding: 'utf8'},
+ );
+ return JSON.parse(fs.readFileSync(path.join(out, 'surface.json'), 'utf8'));
+ };
+
+ it('writes each built package report under the directory and lists it', () => {
+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'api-surface-'));
+ try {
+ // The fixture carries only what the report reads; complete its build.
+ const repo = path.join(tmp, 'repo');
+ fs.cpSync(FIXTURE_ROOT, repo, {recursive: true});
+ for (const f of [
+ 'lib/index.js',
+ 'lib/chip.js',
+ 'lib/internal/secret.js',
+ 'src/demo.css.d.ts',
+ ])
+ fs.writeFileSync(path.join(repo, 'packages/demo', f), '');
+ const out = path.join(tmp, 'surface');
+ expect(surface(repo, out)).toMatchObject({
+ packages: [{name: '@astryxdesign/demo', dir: 'packages/demo'}],
+ skipped: [],
+ });
+ expect(
+ fs.readFileSync(path.join(out, 'packages/demo/api-report.md'), 'utf8'),
+ ).toBe(report);
+ // The checkout's committed reports are left alone.
+ expect(
+ fs.existsSync(path.join(repo, 'packages/demo/api-report.md')),
+ ).toBe(false);
+ } finally {
+ fs.rmSync(tmp, {recursive: true, force: true});
+ }
+ }, 120_000);
+
+ it('lists a package whose build is incomplete as skipped, with no report', () => {
+ const out = fs.mkdtempSync(path.join(os.tmpdir(), 'api-surface-'));
+ try {
+ const {packages, skipped} = surface(FIXTURE_ROOT, out);
+ expect(packages).toEqual([]);
+ expect(skipped).toMatchObject([
+ {
+ name: '@astryxdesign/demo',
+ missing: expect.arrayContaining(['packages/demo/lib/index.js']),
+ },
+ ]);
+ expect(fs.existsSync(path.join(out, 'packages/demo'))).toBe(false);
+ } finally {
+ fs.rmSync(out, {recursive: true, force: true});
+ }
+ }, 120_000);
+});
diff --git a/scripts/api-report/changes.mjs b/scripts/api-report/changes.mjs
index 779514044e..491e37c326 100644
--- a/scripts/api-report/changes.mjs
+++ b/scripts/api-report/changes.mjs
@@ -3,12 +3,13 @@
/**
* @file Compare API reports and render the pull request's API changes.
*
- * @input the merge base's committed reports, the reports generated from the
+ * @input the merge base's reports (built from the merge base, or as committed
+ * there when no build of it was kept), the reports generated from the
* head's build, and the head's committed reports, per package
* @output added, changed, and removed rows per package, each with its
- * signature and a usage example, plus whether the committed report is
- * stale against the head's build; and the advisory Markdown the pull
- * request report embeds
+ * signature and a usage example, plus how many rows the committed
+ * report is behind the head's build; and the advisory Markdown the
+ * pull request report embeds
* @position scripts/api-report — evidence only: nothing here fails a check or
* decides acceptance (architecture:public-component-api INV24, INV13)
*/
@@ -179,22 +180,31 @@ export function usageFor(pkg, row) {
return `import {${name}} from '${spec}'`;
}
+/** The rows one report differs from another by, as the changes list them. */
+const rowCount = ({added, changed, removed}) =>
+ added.length + changed.length + removed.length;
+
/**
- * @param {Array<{pkg: string, base: string|null, head: string, committed: string|null}>} packages
+ * @param {Array<{pkg: string, base: string|null, head: string,
+ * committed: string|null, baseSource?: 'build'|'head'|'committed'}>} packages
*/
export function computeChanges(packages) {
return packages
- .map(({pkg, base, head, committed}) => {
+ .map(({pkg, base, head, committed, baseSource = 'committed'}) => {
// With no report at the merge base there is nothing to compare: the
// package's report is new, and every row would read as added.
const baseline = base == null;
const d = baseline
? {added: [], changed: [], removed: []}
: diffReports(base, head);
+ const stale = committed != null && committed !== head;
return {
pkg,
baseline,
- stale: committed != null && committed !== head,
+ baseSource,
+ stale,
+ // A stale report is one line in the PR report, not its rows.
+ staleRows: stale ? rowCount(diffReports(committed, head)) : 0,
missing: committed == null,
counts: {
added: d.added.length,
@@ -239,22 +249,32 @@ const where = r =>
code([r.entry, r.section, r.item].filter(Boolean).join(' · '));
const short = pkg => code(String(pkg ?? '').replace(/^@astryxdesign\//, ''));
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
/**
* The advisory API changes for the pull request report: one visible summary
* line, with every row inside a closed disclosure.
+ *
+ * Changes from version 2 (each package carries `staleRows`) list only the
+ * rows the pull request changes; a stale committed report is one line naming
+ * how far behind it is. Version 1 changes render as they always did.
* @param {ReturnType<typeof computeChanges>} changes
* @returns {string} empty when nothing changed and every report is current
*/
export function renderChanges(changes) {
- 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,
- );
+ const list = (Array.isArray(changes) ? changes : []).map(c => ({
+ ...c,
+ rows: Array.isArray(c?.rows) ? c.rows : [],
+ }));
+ if (list.some(c => typeof c?.staleRows === 'number'))
+ return renderBuiltChanges(list);
+ const touched = list.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 === true && c.missing !== true)
@@ -270,10 +290,18 @@ export function renderChanges(changes) {
: '';
return `${short(c.pkg)}${counts}${note}`;
});
- const rows = touched.flatMap(c =>
+ return (
+ [`**API changes:** ${parts.join('; ')}`, ...rowTable(touched)].join('\n') +
+ '\n'
+ );
+}
+
+/** The disclosure holding every row, or nothing without rows. */
+function rowTable(packages) {
+ const rows = packages.flatMap(c =>
c.rows.map(r => ({...r, pkg: short(c.pkg)})),
);
- const L = [`**API changes:** ${parts.join('; ')}`];
+ const L = [];
if (rows.length) {
L.push(
'',
@@ -300,5 +328,52 @@ export function renderChanges(changes) {
'</details>',
);
}
+ return L;
+}
+
+/**
+ * Version 2: the summary names only the packages this pull request changes
+ * (or whose report is new or missing); stale committed reports share one line.
+ * @param {ReturnType<typeof computeChanges>} list
+ */
+function renderBuiltChanges(list) {
+ const touched = list.filter(
+ c => c.rows.length || c.missing === true || c.baseline === true,
+ );
+ const stale = list.filter(c => c.stale === true && c.missing !== true);
+ if (!touched.length && !stale.length) return '';
+ const parts = touched.map(c => {
+ if (c.baseline === true && c.missing !== true)
+ return `${short(c.pkg)} new report`;
+ const counts = c.rows.length
+ ? ` +${count(c.counts?.added)} · ~${count(c.counts?.changed)} · −${count(c.counts?.removed)}`
+ : ' no changes';
+ const missing =
+ c.missing === true
+ ? ' (report not committed: run `pnpm api:report`)'
+ : '';
+ // No build of the merge base was kept: rows a stale report at the merge
+ // base carried may show here too.
+ const committed =
+ c.rows.length && c.baseSource === 'committed'
+ ? " (against the merge base's committed report)"
+ : '';
+ return `${short(c.pkg)}${counts}${missing}${committed}`;
+ });
+ const L = [
+ `**API changes:** ${parts.length ? parts.join('; ') : 'none in this pull request'}`,
+ ];
+ if (stale.length) {
+ const behind = stale.map(c =>
+ count(c.staleRows)
+ ? `${short(c.pkg)} ${plural(count(c.staleRows), 'row')}`
+ : short(c.pkg),
+ );
+ L.push(
+ '',
+ `Committed API report behind this build: ${behind.join(', ')}; run \`pnpm api:report\`.`,
+ );
+ }
+ L.push(...rowTable(touched));
return L.join('\n') + '\n';
}
diff --git a/scripts/api-report/cli.mjs b/scripts/api-report/cli.mjs
index 9c103be2bb..ef1982deab 100644
--- a/scripts/api-report/cli.mjs
+++ b/scripts/api-report/cli.mjs
@@ -5,8 +5,11 @@
*
* @input the built published packages (run `pnpm build` first)
* @output `<package>/api-report.md` for each published package; with
- * `--changes`, `api-changes.md` and `api-changes.json` comparing the
- * reports generated from this build with those committed at `--base`
+ * `--surface`, the same reports under another directory (the API
+ * surface Main keeps for each commit, or a merge base built in CI);
+ * with `--changes`, `api-changes.md` and `api-changes.json` comparing
+ * the merge base's surface with the reports generated from this build,
+ * and each committed report with this build
* @position scripts/api-report — the command behind
* architecture:public-component-api INV24
*
@@ -14,8 +17,17 @@
* pnpm api:report write every published package's report
* pnpm api:report --package core write one (name, short name, or directory)
* pnpm api:report --check exit 1 when a committed report is stale
- * node scripts/api-report/cli.mjs --changes --base <ref> [--out <dir>]
+ * node scripts/api-report/cli.mjs --surface <dir> [--root <repo>]
+ * write the built packages' reports to <dir>
+ * (of the checkout at <repo>), committing nothing
+ * node scripts/api-report/cli.mjs --changes --base <ref>
+ * [--base-surface <dir> --base-record main|build] [--out <dir>]
* CI: write the API changes; always exits 0
+ *
+ * The merge base's report for each package comes from, best first: its built
+ * surface (`--base-surface`); this build, when the surface lacks it (a merge
+ * base CI built without that package) and neither its directory nor any of
+ * SHARED_INPUTS changed since `--base`; the report committed at `--base`.
*/
import {execFileSync} from 'node:child_process';
@@ -28,6 +40,9 @@ import {computeChanges, renderChanges} from './changes.mjs';
import {generateReport} from './generate.mjs';
export const REPORT_FILE = 'api-report.md';
+export const SURFACE_FILE = 'surface.json';
+/** api-changes.json's shape; 2 added `baseRecord`, `baseSource`, `staleRows`. */
+export const CHANGES_VERSION = 2;
const REPO_ROOT = path.resolve(
path.dirname(fileURLToPath(import.meta.url)),
'../..',
@@ -60,6 +75,10 @@ function parseArgs(argv) {
base: null,
out: '.',
package: null,
+ surface: null,
+ root: null,
+ baseSurface: null,
+ baseRecord: null,
};
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
@@ -68,6 +87,10 @@ function parseArgs(argv) {
else if (a === '--base') args.base = argv[++i];
else if (a === '--out') args.out = argv[++i];
else if (a === '--package') args.package = argv[++i];
+ else if (a === '--surface') args.surface = argv[++i];
+ else if (a === '--root') args.root = argv[++i];
+ else if (a === '--base-surface') args.baseSurface = argv[++i];
+ else if (a === '--base-record') args.baseRecord = argv[++i];
else throw new Error(`Unknown option: ${a}`);
}
return args;
@@ -91,16 +114,16 @@ function select(packages, wanted) {
}
/** Files an entry point names that the build has not produced. */
-function unbuilt(dir) {
+function unbuilt(dir, root = REPO_ROOT) {
const pkg = JSON.parse(
- fs.readFileSync(path.join(REPO_ROOT, dir, 'package.json'), 'utf8'),
+ fs.readFileSync(path.join(root, dir, 'package.json'), 'utf8'),
);
const missing = [];
const visit = t => {
if (typeof t === 'string') {
// A subpath pattern needs its directory; which files match is reported.
const target = t.includes('*') ? path.dirname(t) : t;
- if (!fs.existsSync(path.join(REPO_ROOT, dir, target)))
+ if (!fs.existsSync(path.join(root, dir, target)))
missing.push(`${dir}/${t.replace(/^\.\//, '')}`);
} else if (t && typeof t === 'object') Object.values(t).forEach(visit);
};
@@ -121,8 +144,108 @@ function showAt(ref, file) {
}
}
+/**
+ * What every report also depends on: themes get their stylesheets from Core
+ * through the CLI; every report reads the CLI's theming targets and the lint
+ * rule's public attributes; declarations come from `tsc` over the root
+ * tsconfig, and stylesheets from the CSS build and StyleX, at the locked
+ * versions.
+ */
+export const SHARED_INPUTS = [
+ 'packages/core',
+ 'packages/cli',
+ 'internal/eslint-plugin-astryx/no-raw-private-attribute.js',
+ 'tsconfig.json',
+ 'pnpm-lock.yaml',
+ 'scripts/build-css.mjs',
+ 'scripts/stylex-module-resolution.cjs',
+ 'scripts/add-declaration-extensions.mjs',
+];
+
+/** Whether a package's report inputs are the same at `ref` as at HEAD. */
+function unchangedSince(ref, dir) {
+ try {
+ execFileSync(
+ 'git',
+ ['diff', '--quiet', ref, 'HEAD', '--', dir, ...SHARED_INPUTS],
+ {
+ cwd: REPO_ROOT,
+ stdio: 'ignore',
+ },
+ );
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+/**
+ * The merge base's report for one package, and where it came from.
+ * @param {{surface: string|null, unchanged: boolean, haveSurface: boolean,
+ * head: string, committedAtBase: string|null}} input
+ * @returns {{base: string|null, baseSource: 'build'|'head'|'committed'}}
+ */
+export function chooseBase({
+ surface,
+ unchanged,
+ haveSurface,
+ head,
+ committedAtBase,
+}) {
+ if (surface != null) return {base: surface, baseSource: 'build'};
+ // A merge base built without this package, which has not changed since.
+ if (haveSurface && unchanged) return {base: head, baseSource: 'head'};
+ return {base: committedAtBase, baseSource: 'committed'};
+}
+
+/**
+ * Write the built packages' reports of the checkout at `root` under `out`,
+ * mirroring their directories, and list them in `surface.json`. A package
+ * whose build is missing is listed as skipped.
+ */
+async function writeSurface(root, out) {
+ const written = [];
+ const skipped = [];
+ for (const p of publishedPackages(root)) {
+ const missing = unbuilt(p.dir, root);
+ if (missing.length) {
+ skipped.push({...p, missing});
+ continue;
+ }
+ const report = await generateReport({repoRoot: root, packageDir: p.dir});
+ const file = path.join(out, p.dir, REPORT_FILE);
+ fs.mkdirSync(path.dirname(file), {recursive: true});
+ fs.writeFileSync(file, report);
+ written.push(p);
+ }
+ fs.mkdirSync(out, {recursive: true});
+ fs.writeFileSync(
+ path.join(out, SURFACE_FILE),
+ JSON.stringify({version: 1, packages: written, skipped}, null, 2) + '\n',
+ );
+ console.log(
+ `API surface: ${written.length} report(s) in ${out}` +
+ (skipped.length
+ ? `; not built: ${skipped.map(p => p.name).join(', ')}`
+ : ''),
+ );
+}
+
+/** A report from a surface directory, or null. */
+function surfaceReport(dir, pkgDir) {
+ const file = path.join(dir, pkgDir, REPORT_FILE);
+ return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+}
+
async function main() {
const args = parseArgs(process.argv.slice(2));
+ if (args.surface) {
+ await writeSurface(
+ args.root ? path.resolve(args.root) : REPO_ROOT,
+ path.resolve(args.surface),
+ );
+ return;
+ }
const packages = select(publishedPackages(REPO_ROOT), args.package);
const missing = packages.flatMap(p => unbuilt(p.dir));
@@ -143,13 +266,27 @@ async function main() {
}
if (args.changes) {
+ const haveSurface =
+ !!args.baseSurface &&
+ fs.existsSync(path.join(args.baseSurface, SURFACE_FILE));
const changes = computeChanges(
- results.map(r => ({
- pkg: r.pkg,
- head: r.head,
- committed: r.committed,
- base: args.base ? showAt(args.base, r.file) : r.committed,
- })),
+ results.map(r => {
+ const dir = path.posix.dirname(r.file);
+ return {
+ pkg: r.pkg,
+ head: r.head,
+ committed: r.committed,
+ ...chooseBase({
+ surface: haveSurface ? surfaceReport(args.baseSurface, dir) : null,
+ haveSurface,
+ unchanged: !!args.base && unchangedSince(args.base, dir),
+ head: r.head,
+ committedAtBase: args.base
+ ? showAt(args.base, r.file)
+ : r.committed,
+ }),
+ };
+ }),
);
fs.mkdirSync(args.out, {recursive: true});
fs.writeFileSync(
@@ -158,12 +295,26 @@ async function main() {
);
fs.writeFileSync(
path.join(args.out, 'api-changes.json'),
- JSON.stringify({version: 1, packages: changes}, null, 2) + '\n',
+ JSON.stringify(
+ {
+ version: CHANGES_VERSION,
+ // Where the merge base's surface came from: Main's record of that
+ // commit, a build of it in this run, or neither (committed reports).
+ baseRecord: haveSurface
+ ? args.baseRecord === 'build'
+ ? 'build'
+ : 'main'
+ : null,
+ packages: changes,
+ },
+ null,
+ 2,
+ ) + '\n',
);
const total = changes.reduce((n, c) => n + c.rows.length, 0);
const stale = changes.filter(c => c.stale || c.missing).map(c => c.pkg);
console.log(
- `API changes: ${total} row(s); stale reports: ${stale.length ? stale.join(', ') : 'none'}`,
+ `API changes: ${total} row(s) against the merge base's ${haveSurface ? `built surface (${args.baseRecord ?? 'main'})` : 'committed reports'}; stale reports: ${stale.length ? stale.join(', ') : 'none'}`,
);
return;
}
diff --git a/scripts/api-report/generate.mjs b/scripts/api-report/generate.mjs
index 8271f3fdf3..0a9fe8e686 100644
--- a/scripts/api-report/generate.mjs
+++ b/scripts/api-report/generate.mjs
@@ -28,14 +28,24 @@ import {fileURLToPath, pathToFileURL} from 'node:url';
const require = createRequire(import.meta.url);
const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-const DISCOVERY = path.join(
- SCRIPT_DIR,
- '../../packages/cli/foundation/discovery',
-);
-const PRIVATE_ATTRIBUTE_RULE = path.join(
- SCRIPT_DIR,
- '../../internal/eslint-plugin-astryx/no-raw-private-attribute.js',
-);
+const THEMING_TARGETS = 'packages/cli/foundation/discovery/theming-targets.mjs';
+const PRIVATE_ATTRIBUTE_RULE =
+ 'internal/eslint-plugin-astryx/no-raw-private-attribute.js';
+
+/**
+ * A module the report reads its lists from, as the reported repository holds
+ * it: a merge base is reported with its own theming targets and public
+ * attributes. A tree without the module (a test fixture) uses this one's.
+ * @param {string} repoRoot
+ * @param {string} file
+ * @returns {string}
+ */
+const listModule = (repoRoot, file) => {
+ const own = path.join(repoRoot, file);
+ return pathToFileURL(
+ fs.existsSync(own) ? own : path.join(SCRIPT_DIR, '../..', file),
+ ).href;
+};
const CODE = /\.(m|c)?(t|j)sx?$/;
const CSS = /\.css$/;
@@ -540,7 +550,7 @@ export async function generateReport(opts) {
if (fs.existsSync(src)) {
// The CLI's enumeration is the one list theme authors see; reuse it.
const {collectThemingTargets} = await import(
- pathToFileURL(path.join(DISCOVERY, 'theming-targets.mjs')).href
+ listModule(repoRoot, THEMING_TARGETS)
);
for (const t of await collectThemingTargets(src)) {
const props = [...t.props].sort(byName);
@@ -574,7 +584,7 @@ export async function generateReport(opts) {
const haystack = built.join('\n');
// INV23's list, as the lint rule that enforces it holds it.
const {PUBLIC_ATTRIBUTES} = await import(
- pathToFileURL(PRIVATE_ATTRIBUTE_RULE).href
+ listModule(repoRoot, PRIVATE_ATTRIBUTE_RULE)
);
const publicAttributes = [...PUBLIC_ATTRIBUTES]
.map(name => `data-astryx-${name}`)