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.mjsindex 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.ymlindex 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 baseid: merge-baseif: 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 recordid: base-buildif: 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=SC2016nohup 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 buildpnpm -F @astryxdesign/core buildfor pkg in lab charts richtext vega; dogit diff --quiet "$BASE_SHA" "$HEAD_SHA" -- "packages/$pkg/src" || pnpm -F "@astryxdesign/$pkg" builddonenode ../.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."+ fitouch ../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 artifactif: 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.ymlindex 7685341dd6..6957081c44 100644--- a/.github/workflows/deploy.yml+++ b/.github/workflows/deploy.yml@@ -238,6 +238,24 @@ jobs:path: package-size.jsonretention-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 exportsrun: node scripts/verify-exports.mjsdiff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.mdindex 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 boundaryappears 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 addedor changed row of a pull request's API changes with current records. A rowthat 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 prefixedprops 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 includePowerSearch's `startIcon` and `endContent`, SideNav's `topContent`,`footer`, and `footerIcons`, Tokenizer's `startIcon`, DropdownMenu'sdiff --git a/scripts/api-report/api-report.test.mjs b/scripts/api-report/api-report.test.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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}`)