Skip to content

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.md
new file mode 100644
index 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.
+
+@vjeux
diff --git a/packages/cli/scripts/sync-api-types.mjs b/packages/cli/scripts/sync-api-types.mjs
index 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.mjs
new file mode 100644
index 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);
+});