An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @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 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
* entry points, and `foundation` is included because the `api` declarations
* re-export from it — without it a consumer resolving those re-exports hits
* TS7016 on the packed surface.
*
* The emitted `.d.mts` are NOT committed (they're gitignored, like the other
* packages' `dist/`). This script runs automatically at `prepack`, so
* `pnpm pack`/`pnpm publish` always ships a freshly generated, in-sync surface.
* Run `pnpm sync:api-types` to produce them locally; the published surface is
* verified end-to-end by `.github/scripts/cli-api-types-verify.mjs`.
*
* @position packages/cli/scripts — build tooling; not shipped runtime
*/
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)), '..');
/**
* The source trees whose `.mjs` JSDoc is the contract. Emitted in one tsc pass
* (they share types), then copied back beside their sources.
*
* `foundation` is here because the published `./api` declarations re-export
* from it (e.g. api/template re-exports the template adapter): a consumer
* resolving those re-exports needs foundation's declarations too, or it hits
* TS7016 on the packed surface.
*/
const TREES = ['api', 'authoring', 'foundation'];
/**
* Banner prepended to every emitted declaration so it's obvious the file is
* generated and must not be hand-edited — edit the `.mjs` JSDoc and re-run
* `pnpm sync:api-types` instead. The `@generated` tag is the standard marker
* tooling and reviewers recognize.
* @param {string} tree
*/
const banner = tree =>
`// @generated by scripts/sync-api-types.mjs from the JSDoc in ${tree}/**/*.mjs.\n` +
'// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.\n\n';
/**
* Recursively copy every emitted declaration from `src` to `dest`, preserving
* structure and prepending the generated banner.
* @param {string} src
* @param {string} dest
* @param {string} tree
*/
function copyDts(src, dest, tree) {
for (const entry of fs.readdirSync(src, {withFileTypes: true})) {
const s = path.join(src, entry.name);
const d = path.join(dest, entry.name);
if (entry.isDirectory()) {
copyDts(s, d, tree);
} else if (entry.name.endsWith('.d.mts')) {
fs.mkdirSync(dest, {recursive: true});
fs.writeFileSync(d, banner(tree) + fs.readFileSync(s, 'utf8'));
}
}
}
/**
* Recursively delete every `.d.mts` under `dir` so a regen builds from pure
* `.mjs` source. Committed declarations sit next to their `.mjs`, and tsc would
* otherwise resolve an import to the stale `.d.mts` instead of re-inferring from
* the (possibly edited) source — making generation non-idempotent.
* @param {string} dir
*/
function cleanDts(dir) {
if (!fs.existsSync(dir)) return;
for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
const p = path.join(dir, entry.name);
if (entry.isDirectory()) cleanDts(p);
else if (entry.name.endsWith('.d.mts')) fs.rmSync(p);
}
}
/**
* 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));
// 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);
}
} finally {
fs.rmSync(tmp, {recursive: true, force: true});
}
console.log(`Synced ${TREES.join(' + ')} declarations from the JSDoc source of truth.`);