An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): sync:api-types emits into a temp directory of its own (#8412)
Christopher Chedeaudf92fb83c95a
diff --git a/.changeset/sync-api-types-temp-dir.md b/.changeset/sync-api-types-temp-dir.mdnew file mode 100644index 0000000000..cfebb38c8b--- /dev/null+++ b/.changeset/sync-api-types-temp-dir.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[chore] Internal: generating the CLI's type declarations no longer fails when builds in two checkouts run at once on one machine, and it no longer needs pnpm on PATH.++@vjeuxdiff --git a/packages/cli/scripts/sync-api-types.mjs b/packages/cli/scripts/sync-api-types.mjsindex 089a9756e8..f6f8447cbd 100644--- a/packages/cli/scripts/sync-api-types.mjs+++ b/packages/cli/scripts/sync-api-types.mjs@@ -4,11 +4,12 @@* @file Generate the published type surface from the JSDoc source of truth.** Functions own their types: a leaf's `@returns` + its colocated `.type.mjs`- * typedefs ARE the contract. This script runs `tsc` (allowJs + checkJs +- * declaration + emitDeclarationOnly) over the source trees into a throwaway- * temp dir, then copies the emitted declaration trees (the `.d.mts` files) back- * alongside their sources (so relative imports and shared `types` declarations- * resolve). `api/index.d.mts` is the entry `package.json` exports["./api"].types+ * typedefs ARE the contract. This script runs TypeScript's `tsc` script+ * through this Node, with no shell and no `pnpm` on PATH. It runs it over the+ * source trees (allowJs + checkJs + declaration + emitDeclarationOnly) into a+ * throwaway temp dir. Then it copies the emitted `.d.mts` trees back beside+ * their sources, so relative imports and shared `types` declarations resolve.+ * `api/index.d.mts` is the entry `package.json` exports["./api"].types* points at.** Three trees are emitted (see TREES): `api` and `authoring` are published@@ -27,11 +28,12 @@import {execFileSync} from 'node:child_process';import * as fs from 'node:fs';+import {createRequire} from 'node:module';+import * as os from 'node:os';import * as path from 'node:path';import {fileURLToPath} from 'node:url';const CLI_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');-const TMP = '/tmp/astryx-dts-build';/*** The source trees whose `.mjs` JSDoc is the contract. Emitted in one tsc pass@@ -91,18 +93,40 @@ function cleanDts(dir) {}}-fs.rmSync(TMP, {recursive: true, force: true});+/**+ * The TypeScript compiler's `tsc` script, as the CLI package resolves+ * `typescript`. It runs through this Node: Windows cannot spawn `pnpm` by name+ * without a shell.+ * @returns {string}+ */+function tscScript() {+ const manifest = createRequire(path.join(CLI_ROOT, 'package.json')).resolve(+ 'typescript/package.json',+ );+ const {bin} = JSON.parse(fs.readFileSync(manifest, 'utf8'));+ return path.join(path.dirname(manifest), typeof bin === 'string' ? bin : bin.tsc);+}+for (const tree of TREES) cleanDts(path.join(CLI_ROOT, tree));-execFileSync('pnpm', ['exec', 'tsc', '--project', 'tsconfig.api-dts.json'], {- cwd: CLI_ROOT,- stdio: 'inherit',-});-for (const tree of TREES) {- const emitted = path.join(TMP, 'packages', 'cli', tree);- if (!fs.existsSync(emitted)) {- throw new Error(`Expected emitted declarations at ${emitted} — tsc produced nothing.`);+// Each run emits into a temp directory of its own, passed to tsc as --outDir.+// Two builds on one machine (two checkouts, or two jobs) can run this at once.+// With a shared directory, one run's cleanup deletes what the other just+// emitted.+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-dts-build-'));+try {+ execFileSync(+ process.execPath,+ [tscScript(), '--project', 'tsconfig.api-dts.json', '--outDir', tmp],+ {cwd: CLI_ROOT, stdio: 'inherit'},+ );+ for (const tree of TREES) {+ const emitted = path.join(tmp, 'packages', 'cli', tree);+ if (!fs.existsSync(emitted)) {+ throw new Error(`Expected emitted declarations at ${emitted} — tsc produced nothing.`);+ }+ copyDts(emitted, path.join(CLI_ROOT, tree), tree);}- copyDts(emitted, path.join(CLI_ROOT, tree), tree);+} finally {+ fs.rmSync(tmp, {recursive: true, force: true});}-fs.rmSync(TMP, {recursive: true, force: true});console.log(`Synced ${TREES.join(' + ')} declarations from the JSDoc source of truth.`);diff --git a/packages/cli/scripts/sync-api-types.test.mjs b/packages/cli/scripts/sync-api-types.test.mjsnew file mode 100644index 0000000000..4b6d2a979f--- /dev/null+++ b/packages/cli/scripts/sync-api-types.test.mjs@@ -0,0 +1,186 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Two `sync:api-types` runs at once must not share a temp directory.+ *+ * Two builds on one machine (two checkouts, or two jobs) each run the sync. A+ * shared output directory lets one run's cleanup delete the declarations the+ * other has just emitted, which then fails with "tsc produced nothing". This+ * runs a copy of the script twice in a scratch package. Its `typescript` is a+ * stand-in `tsc` that emits a stub declaration per tree, with nothing on PATH.+ * The script runs `tsc` through Node, so it needs no `pnpm` there. The test+ * forces the losing order: the second run starts after the first has emitted+ * and before the first reads its output.+ */++import {spawn} 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 {afterEach, describe, expect, it} from 'vitest';++const SCRIPT = path.join(+ path.dirname(fileURLToPath(import.meta.url)),+ 'sync-api-types.mjs',+);+const TREES = ['api', 'authoring', 'foundation'];+const CONFIG_OUT_DIR = JSON.parse(+ fs.readFileSync(+ path.join(path.dirname(SCRIPT), '..', 'tsconfig.api-dts.json'),+ 'utf8',+ ),+).compilerOptions.outDir;++/**+ * The stand-in for TypeScript's `tsc` script: `tsc --project <config>+ * [--outDir <dir>]` emits `<outDir>/packages/cli/<tree>/index.d.mts` for each+ * tree, where the output directory is `--outDir` or the config's own. The role+ * in `SYNC_TEST_ROLE` orders the two runs through files in `SYNC_TEST_DIR`.+ */+const FAKE_TSC = `const fs = require('node:fs');+const path = require('node:path');+const args = process.argv.slice(2);+const flag = name => {+ const i = args.indexOf(name);+ return i === -1 ? undefined : args[i + 1];+};+const config = JSON.parse(fs.readFileSync(flag('--project'), 'utf8'));+const outDir = flag('--outDir') ?? config.compilerOptions.outDir;+const sync = process.env.SYNC_TEST_DIR;+const waitFor = name => {+ const deadline = Date.now() + 20000;+ while (!fs.existsSync(path.join(sync, name))) {+ if (Date.now() > deadline) throw new Error('timed out waiting for ' + name);+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);+ }+};+const emit = () => {+ for (const tree of ${JSON.stringify(TREES)}) {+ const dir = path.join(outDir, 'packages', 'cli', tree);+ fs.mkdirSync(dir, {recursive: true});+ fs.writeFileSync(path.join(dir, 'index.d.mts'), 'export {};\\n');+ }+};+if (process.env.SYNC_TEST_ROLE === 'first') {+ emit();+ fs.writeFileSync(path.join(sync, 'first-emitted'), '');+ waitFor('second-compiling');+} else {+ fs.writeFileSync(path.join(sync, 'second-compiling'), '');+ waitFor('first-done');+ emit();+}+`;++/** @type {string[]} */+const scratch = [];+afterEach(() => {+ for (const dir of scratch.splice(0)) {+ fs.rmSync(dir, {recursive: true, force: true});+ }+});++/**+ * A scratch CLI package with a copy of the script and a stand-in `typescript`+ * package. Its PATH directory is empty: the script needs no `pnpm` there.+ */+function makeScratchPackage() {+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'sync-api-types-test-'));+ scratch.push(root);+ const cli = path.join(root, 'packages', 'cli');+ fs.mkdirSync(path.join(cli, 'scripts'), {recursive: true});+ fs.copyFileSync(SCRIPT, path.join(cli, 'scripts', 'sync-api-types.mjs'));+ for (const tree of TREES) {+ fs.mkdirSync(path.join(cli, tree), {recursive: true});+ fs.writeFileSync(path.join(cli, tree, 'index.mjs'), 'export {};\n');+ }+ // The real config's output directory: where a run that does not choose its+ // own emits, the same path for every run.+ fs.writeFileSync(+ path.join(cli, 'tsconfig.api-dts.json'),+ JSON.stringify({compilerOptions: {outDir: CONFIG_OUT_DIR}}),+ );+ const typescript = path.join(cli, 'node_modules', 'typescript');+ fs.mkdirSync(path.join(typescript, 'bin'), {recursive: true});+ fs.writeFileSync(+ path.join(typescript, 'package.json'),+ JSON.stringify({name: 'typescript', bin: {tsc: './bin/tsc'}}),+ );+ fs.writeFileSync(path.join(typescript, 'bin', 'tsc'), FAKE_TSC);+ const bin = path.join(root, 'bin');+ fs.mkdirSync(bin);+ const sync = path.join(root, 'sync');+ fs.mkdirSync(sync);+ return {cli, bin, sync};+}++/**+ * @param {{cli: string, bin: string, sync: string}} pkg+ * @param {'first' | 'second'} role+ * @returns {Promise<{code: number | null, output: string}>}+ */+function runSync(pkg, role) {+ return new Promise(resolve => {+ const child = spawn(+ process.execPath,+ [path.join(pkg.cli, 'scripts', 'sync-api-types.mjs')],+ {+ cwd: pkg.cli,+ env: {+ ...process.env,+ PATH: pkg.bin,+ SYNC_TEST_DIR: pkg.sync,+ SYNC_TEST_ROLE: role,+ },+ stdio: ['ignore', 'pipe', 'pipe'],+ },+ );+ let output = '';+ child.stdout.on('data', chunk => (output += chunk));+ child.stderr.on('data', chunk => (output += chunk));+ child.on('close', code => resolve({code, output}));+ });+}++/** @param {string} file */+async function waitForFile(file) {+ const deadline = Date.now() + 20000;+ while (!fs.existsSync(file)) {+ if (Date.now() > deadline) throw new Error(`timed out waiting for ${file}`);+ await new Promise(resolve => setTimeout(resolve, 10));+ }+}++describe('sync-api-types', () => {+ it('a run syncs the emitted declarations beside their sources', async () => {+ const pkg = makeScratchPackage();+ fs.writeFileSync(path.join(pkg.sync, 'second-compiling'), '');+ const result = await runSync(pkg, 'first');++ expect(result.code, result.output).toBe(0);+ for (const tree of TREES) {+ expect(+ fs.readFileSync(path.join(pkg.cli, tree, 'index.d.mts'), 'utf8'),+ ).toContain('@generated by scripts/sync-api-types.mjs');+ }+ });++ it('two runs at once each keep their own emitted declarations', async () => {+ const pkg = makeScratchPackage();+ const first = runSync(pkg, 'first');+ await waitForFile(path.join(pkg.sync, 'first-emitted'));+ const second = runSync(pkg, 'second');+ const firstResult = await first;+ fs.writeFileSync(path.join(pkg.sync, 'first-done'), '');+ const secondResult = await second;++ expect(firstResult.code, firstResult.output).toBe(0);+ expect(secondResult.code, secondResult.output).toBe(0);+ for (const tree of TREES) {+ expect(+ fs.readFileSync(path.join(pkg.cli, tree, 'index.d.mts'), 'utf8'),+ ).toContain('@generated by scripts/sync-api-types.mjs');+ }+ }, 60000);+});